Skip to main content

Storyblok

Plugin for Gesso CMS Provider​

Requirements​

Environment Variables​

Required for the integration to work properly.

  • NEXT_PUBLIC_CMS_URL - Storyblok API URL
  • CMS_PREVIEW_SECRET - Preview secret for the CMS
  • STORYBLOK_ACCESS_TOKEN - Storyblok access token

Setting up Storyblok instance​

Create a Storyblok space

  • Get the space ID from the url. https://app.storyblok.com/#!/me/spaces/<space_id>
  • Get the access token from the settings. /settings?tab=api
info

Note: The access token requires preview access permissions to work with the preview mode.

API URL depends on the region of the Storyblok space. Storyblok DOCS

  • EU region: https://gapi.storyblok.com/v1/api
  • US region: https://gapi-us.storyblok.com/v1/api
  • CA region: https://gapi-ca.storyblok.com/v1/api

Generate a preview secret for the CMS preview mode.

  • openssl rand -base64 16

Create an OAuth token for the Storyblok setup script.

  • Go to https://app.storyblok.com/#/me/account?tab=token and create a new token. (This is used for initial setup only and is not required to integrate storyblok)

Importing the Gesso components​

Gesso stores the default components in gesso-storyblok/exports If you are looking to setup a new Storyblok space with Gesso components, you can use the exports/all/components.gesso.json file to import all the components at once.

Download the json file and store it somewhere locally.

To import the components into a Storyblok space, you can use the Storyblok CLI.

  • pnpm i -g storyblok: Install the Storyblok CLI
  • pnpx storyblok login: Authenticate with storyblok
  • pnpx storyblok spaces: Get the space ID for the Storyblok space you want to import into
  • pnpx storyblok push-components -s <space_id> path/to/components.gesso.json: Push the components to the Storyblok space
info

The CLI doesn't handle clashes with existing components. If you have groups/components with the same name, you will need to handle this manually. It's best to import before adding any custom components to the space.

Preview Mode​

To enable the preview mode in Storyblok, go to https://app.storyblok.com/#/me/spaces/<space_id>/settings?tab=editor

  • Preview URLS:
    • https://<your-site-url>/api/preview?secret=<your_preview_secret>&resourceVersion=draft&slug=/ - Production
    • https://localhost:3010/api/preview?secret=<your_preview_secret>&resourceVersion=draft&slug=/ - Local development
info

PREVIEW URL: the slug needs to be / for the preview mode to work with Gesso's out of the box setup. Storyblok will append the content route to this such as some/page

LOCAL PREVIEW: To connect your local development site to Storyblok you must have a valid SSL certificate. An easy way to do this is to use local-ssl-proxy package Then to proxy the local development server to a secure connection run:

local-ssl-proxy --source 3000 --target 3010

Registering hooks​

info

Note: This is only required for manual setup. The gesso starter-kit already has this setup.

Create a src/cms.ts file. In that file register the Storyblok plugins with the CMS Provider.

import { CMS, cms as gessoCMS } from '@acromedia/gesso-cms';
import plugins from '@acromedia/gesso-storyblok';
import config from '../gesso.config.json';

const cms: CMS = gessoCMS(plugins, config);

export { cms };

Limitations​

  • Accounts: Storyblok does not handle user authentication, you will need to use a third-party auth services such as Auth0
  • Forms: Storyblok handles building forms, but does not handle collecting form data. You will need to connect a third-party such as HubSpot to capture form submissions.