How to generate pages by createPages API with Gatsby.js
Storyblok is the first headless CMS that works for developers & marketers alike.
This tutorial will explore integrating Storyblok into a Gatsby.js site with createPages API and enabling the live preview in the Visual Editor. We will use the gatsby-source-storyblok plugin to load our data from Storyblok and enable the Storyblok Bridge to preview our changes.
You can find all the code for this tutorial and commits in our gatsby-storyblok-boilerplate repo. You can also follow the video below, which guides you through all the steps.
Officially, Gatsby.js recommends generating pages dynamically with their File System Route API. Please check our Add a headless CMS to Gatsby.js in 5 minutes tutorial .
Requirements
To follow this tutorial, there are the following requirements:
- Basic understanding of Gatsby.js and React
- Node, yarn (or npm), and Gatsby installed
- An account on Storyblok to manage content
- A new Storyblok space
The project in this article was developed using the following versions of these technologies:
- Gatsby ^4.6.1
- Nodejs v16.13.2
- npm v8.1.2
Keep in mind that these versions may be slightly behind the latest ones.
Adding Dynamic Components
Now that we kickstarted our project and have a simple connection to Storyblok, we want to load components dynamically. We will create two files in the component folder: dynamicComponent.js
and teaser.js
Loading Dynamic Components
Finally, we need to add the last part to our pages/index.js
file to display our components.
If you added a Title field to the page component {1} by defining the schema (see video around minute 19:00), you should be able to see the title. Then the components should be loaded {2} automatically. If the component is not defined in your component/dynamicComponent.js
file, you will see the fallback text {3}.
You can check the commit feat: add storyblok source plugin to index and feat: add dynamic component for the changes.
Enabling the Visual Editor & Live Preview
So far we loaded our content from Storyblok, but we aren't able to directly select the different components. To enable Storyblok's Visual Editor, we need to connect the Storyblok Bridge. For this tutorial, we will already use the new Storyblok Bridge Version 2. After loading the bridge, we will need to add a React hook to enable live updating of the story content.
Adding the Storyblok Bridge
To do that we have to add a specific <script>
tag to the end of our document, whenever we want to enable it. This is mostly the case when you're inside the Storyblok editor. By wrapping the page in a component with sbEditable
function, we also make the page fields like the title
clickable.
Inside our lib/storyblok.js
file, add the following code after the client. In Line 12, we're creating a custom React hook called useStoryblok
.
Inside this hook, we have a function addBridge
(Line 39), which basically just adds the script tag, if it's not already present. Once the loading of the bridge is completed (Line 58), it will call the initEventListeners
function (Line 17) to enable input
(Line 25) and published
and change
events (Line 22) inside Storyblok. We could also make use of the enterEditmode
event to load the draft story when the editor is open.
Finally, we need to load this hook in our pages/index.js
file on Line 13. We will also move the parsing of the story content to the lib/storyblok.js
file.
If the connection with the Storyblok hook is working, you should be able to select the component directly.
You can check the commit feat: add storyblok bridge and live updates for the changes.
Automatic Page Generation
In most cases, you would want to automatically generate the pages from the content you have set up in Storyblok. To do that with Gatsby, we can follow this tutorial. Basically, what we need to do is to add a template file: templates/page.js
as well as change our gatsby-node.js
.
Let's start by creating the template, similar to our pages/index.js
. Create a new folder templates
with a file page.js
:
The biggest difference to the pages/index.js
is that it's not using GraphQl directly on the page, but exposing the story via the pageContext
object.
To get that working we also need to add some logic to our gatsby-node.js
file.
On Line 7, we're loading our template we just created for all pages. On Line 10 we're requesting all stories from Storyblok with the content type Page. On Line 35, we're creating the actual pages, but are skipping the Home story, because we're already loading that one in the index.js
file.
When we create a new entry in Storyblok, saving it, and restarting the development server (or using the refresh button in the GraphiQL explorer), the new page should now be visible on your localhost.
You can check the commit feat: automatic page generation for the changes.
Resource | Link |
---|---|
Github Repository | https://github.com/storyblok/gatsby-storyblok-boilerplate |
Youtube Video | https://www.youtube.com/watch?v=got3f860O-8 |
Gatsby Source Storyblok Plugin | https://github.com/storyblok/gatsby-source-storyblok |
Storyblok Bridge Documentation | https://www.storyblok.com/docs/Guides/storyblok-latest-js |
Gatsby Refresh Content Docs | https://www.gatsbyjs.com/docs/refreshing-content/ |
Gatsby Page Generation Tutorial | https://www.gatsbyjs.com/docs/tutorial/part-seven/ |