Setup Storyblok

Setup Storyblok 🧱

Storyblok is an extremely powerful, easy-to-use, headless CMS. We can use a visual builder to create pages, and then pull those pages into our Next.js app via the Storyblok content delivery API.

In this section, we'll put most of our focus on building the pages within the Storyblok website, then we will finish up with reviewing how it all connects within the codebase. I think this will make the code easier to understand but feel free to read the code review first.

In your new template, you will find an extra directory of goodies: apps/web/src/storyblok.

You have multiple Storyblok components already pre-defined, and the layouts which are being consumed in the apps/web/src/app/blogs and the apps/web/src/app/docs directories.

We will push the apps/web/src/storyblok/sb-components.jsonto your space to pre-populate your components.

There is also a script: apps/web/src/storyblok/quickstart.sh . This will pre-populate your Storyblok stories to speed things up.

Create your Storyblok space

  • Create a free Storyblok account.

  • Create a space. Choose your region and remember this.

  • In your Space Settings, go to Access Tokens and create a Preview Access token. Add this to your .env.local under STORKBLOK_ACCESS_TOKEN.

  • Also, open the apps/web/src/storyblok/utils/initialiseStoryblok.ts file and set your region under the apiOptions key.

Push your components

  • Under My Account > Account Settings > Security > Personal access token generate a personal access token and copy it. You will use this later as well to create stories, so paste it somewhere handy.

  • Install the Storyblok CLI with npm i storyblok -g

  • Login to the CLI storyblok login . Use your PAT and choose the region you created the space in.

  • In your space, go to settings and take note of your Space ID.

  • From the root of the monorepo, run the following:

storyblok push-components apps/web/src/storyblok/sb-components.json --space YOUR_SPACE_ID

Once that completes, you will see a list of components in the Block Library of your space.

Create stories

  • In the quickstart.sh script, at the top, paste your token into the variable OAUTH_TOKEN.

  • Add your Space ID to the SPACE_ID variable.

  • Uncomment the REGION_URL variable that you are using.

  • In the terminal, from the root of the monorepo, run the following command:

zsh apps/web/src/storyblok/quickstart.sh

And you should now have a rough hierarchy loaded into the Content section of your space.

Add content to stories

Now we'll add some content to these Stories that we've created so our app actually shows something!

Authors

In the Storyblok website, goto Content > Authors > Mc Lovin. You might see a screen about setting up the visual editor. This won't be useful for our Author, but go ahead and click Save and show anyway.

In the Edit panel (or just click the Form editor on the left), fill out the details. Save and Publish the content.

Note: If there is any "Fields out of schema", you can remove these.

Blogs

Over to Content > Blogs > Post 1. Post 1 uses the Content-Type blogPage . Which means it inherits all of the fields you see to the right.

  • Fill out the meta info for the page if you like.

  • Add a header by pressing the plus

  • Choose your Author

  • And just put some text into the rich text editor.

  • Hit save, and then click the settings cog next to the URL in the preview panel. Set your default location to https://localhost:3000/ save it, then navigate back to the blog post.

You should have your first blog post!

Have a play with the other fields to see what they do. Then navigate to the Blogs via the nav menu and you will see recently published blogs!

Docs

Firstly, we need to clean up the docs hierarchy.

  • Go to Content > Docs, then select the Home page and click Settings.

  • Check the box to Define as root for the folder. Save the changes.

  • In Group 1 Folder, you might like to rearrange the order of the pages.

Now go back and click into the Docs Home page to edit it. You'll see the menu hierarchy looks good now! Because the docs home page uses the Page Content Type, you can add a list of blocks to the body.

Products

Now just like we did with Authors, go to Content > Products > Product 1 and click Form on the left. Create the first product there and then click Publish.

Back to the Docs Home Page: Content > Docs > Home and just under the Divider, insert the Product Cards component and click Save. Now you have inserted your Product Cards component into the page!

Code Review

Now we've got familiar with the Storyblok visual builder, lets have a think about how the code makes this happen!

Basic Setup

Open apps/web/src/storyblok/utils/initialiseStoryblok.ts . Really, this is the magic – in this initialisation, we map the Storyblok Blocks, to our React components.

The process generally goes:

  1. Create a Block on the Storyblok portal.

  2. Add fields to it (these are the props for your React component).

  3. Use the CLI to pull down the components.json, and use the storyblok-generate-ts package to generate TS types from that file.

  4. Map that component to your own react component.

Lets do that.

  • In the package.json of the web package, edit the sb:typegen script to include your Space ID.

  • From the root of the monorepo, run yarn web sb:typegen . This will populate the file apps/web/src/storyblok/sb-types.d.ts .

  • In the apps/web/src/storyblok/utils/initialiseStoryblok.ts file, CMD-Click into the SbPageHeading component.

  • Here, you can see the pattern of typing the props, and then creating your component.

Dynamic routes

Go to the file apps/web/src/app/docs/[...slug]/page.tsx . This is quite straight forward:

  • We construct our fetching function setting the root of the fetch to the docs path.

  • We make draft stories viewable while we are working locally.

  • We take the slug of the dynamic route, and fetch the corresponding story.

  • We use the StoryblokComponent which, in this case, would receive a docPage Content Type from the fetch, and forward that to the docPage component we mapped in the initialisation.

  • Now hop over to apps/web/src/storyblok/components/SbDocPage.tsx and you can see that we take the fields we setup in Storyblok and configure a generic doc page layout!

  • Note that the root docs page simply maps all the components it is provided, and uses the StoryblokComponent to convert each to the corresponding React component. This way it is more flexible.

Last updated Mon Aug 26 2024

Getting started