Storyblok & Astro
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
Storyblok is a component-based headless CMS that allows you to manage your content using reusable components called Bloks.
Integrating with Astro
Section titled Integrating with AstroIn this section, you will use the Storyblok integration to connect Storyblok to Astro.
Prerequisites
Section titled PrerequisitesTo get started, you will need to have the following:
-
An Astro project - If you don’t have an Astro project yet, our Installation guide will get you up and running in no time.
-
A Storyblok account and space - If you don’t have an account yet, sign up for free and create a new space.
-
Storyblok Preview token - This token will be used to fetch drafts and published versions of your content. You can find and generate your API token in the Access Tokens tab of your Storyblok space settings.
Setting up credentials
Section titled Setting up credentialsTo add your Storyblok credentials to Astro, create a .env
file in the root of your project with the following variable:
Now, you should be able to use these environment variables in your project.
Your root directory should now include this new file:
Directorysrc/
- …
- .env
- astro.config.mjs
- package.json
Installing dependencies
Section titled Installing dependenciesTo connect Astro with your Storyblok space, install the official Storyblok integration using the command below for your preferred package manager:
Configuring Storyblok
Section titled Configuring StoryblokModify your Astro config file to include the Storyblok integration:
The Storyblok integration requires an object with the following properties:
-
accessToken
- This references the Storyblok API token that you added in the previous step.Since the Astro config file does not normally support environment variables, use the
loadEnv
function from Vite to load them. -
components
- An object that maps Storyblok component names to paths to your local components. This is required to render your Storyblok Bloks in Astro.The component paths are relative to the
src
directory. For example, if your component is located atsrc/storyblok/MyComponent.astro
, the path would bestoryblok/MyComponent
(without the.astro
extension). -
apiOptions
- An object containing Storyblok API options.By default, the region is
eu
. If your Storyblok space was created in the US region, you will need to set the region tous
.
Connecting Bloks to Astro components
Section titled Connecting Bloks to Astro componentsTo connect your Bloks to Astro, create a new folder named storyblok
in the src
directory. This folder will contain all the Astro components that will match your Bloks in your Storyblok Blok library.
In this example, you have a blogPost
Blok content type in your Storyblok library with the following fields:
title
- A text fielddescription
- A text fieldcontent
- A rich text field
Our goal is to create the equivalent Astro component that will use these fields to render its content. To do this, create a new file named BlogPost.astro
inside src/storyblok
with the following content:
The blok
property contains the data that you will receive from Storyblok. It also contains the fields that were defined in the blogPost
content type Blok in Storyblok.
To render our content, the integration provides utility functions such as:
storyblokEditable
- it adds the necessary attributes to the elements so that you can edit them in Storyblok.renderRichText
- it transforms the rich text field into HTML.
Your root directory should include this new file:
Directorysrc/
Directorystoryblok/
- BlogPost.astro
- .env
- astro.config.mjs
- package.json
Finally, to connect the blogPost
Blok to the BlogPost
component, add a new property to your components object in your Astro config file.
- The key is the name of the Blok in Storyblok. In this case, it is
blogPost
. - The value is the path to the component. In this case, it is
storyblok/BlogPost
.
The key
should exactly match your Blok name in Storyblok to be referenced correctly. If these don’t match, or you’re trying to reference a component that doesn’t exist in Storyblok, you’ll get an error.
Fetching data
Section titled Fetching dataTo test the setup, in Storyblok create a new story with the blogPost
content type named test-post
.
In Astro, create a new page in the src/pages/
directory named test-post.astro
with the following content:
To query your data, use the useStoryblokApi
hook. This will initialize a new client instance using your integration configuration.
To render your content, pass the content
property of the Story to the StoryblokComponent
as a blok
prop. This component will render the Bloks that are defined inside the content
property. In this case, it will render the BlogPost
component.
Making a blog with Astro and Storyblok
Section titled Making a blog with Astro and StoryblokWith the integration set up, you can now create a blog with Astro and Storyblok.
Prerequisites
Section titled Prerequisites-
A Storyblok space - For this tutorial, we recommend using a new space. If you already have a space with Bloks, feel free to use them, but you will need to modify the code to match the Blok names and content types.
-
An Astro project integrated with Storyblok - See integrating with Astro for instructions on how to set up the integration.
Creating a blok library
Section titled Creating a blok libraryTo create Bloks, go to the Storyblok app and click on the Block Library tab. Click on the + New blok button and create the following Bloks:
-
blogPost
- A content type Blok with the following fields:title
- A text fielddescription
- A text fieldcontent
- A rich text field
-
blogPostList
- An empty nestable Blok -
page
- A content type Blok with the following fields:body
- A nestable Blok
Creating content
Section titled Creating contentTo add new content, go to the content section by clicking on the Content tab. Using the Blok library that you created in the previous step, create the following stories:
-
home
- A content type story with thepage
Blok. Inside thebody
field, add ablogPostList
Blok. -
blog/no-javascript
- A story with theblogPost
content type inside the blog folder. -
blog/astro-is-amazing
- A story with theblogPost
content type inside the blog folder.
Now that you have your content ready, return to your Astro project and start building your blog.
Connecting Bloks to components
Section titled Connecting Bloks to componentsTo connect your newly created Bloks to Astro components, create a new folder named storyblok
in your src
directory and add the following files:
Page.astro
is a nestable Block content type component that will recursively render all the Bloks inside the body
property of the page
Blok. It also adds the storyblokEditable
attributes to the parent element which will allow us to edit the page in Storyblok.
BlogPost.astro
will render the title
, description
and content
properties of the blogPost
Blok.
To transform the content
property from a rich text field to HTML, you can use the renderRichText
helper function.
BlogPostList.astro
is a nestable Blok content type component that will render a list of blog post previews.
It uses the useStoryblokApi
hook to fetch all the stories with the content type of blogPost
. It uses the version
query parameter to fetch the draft versions of the stories when in development mode and the published versions when building for production.
Astro.props
is used to set up the editor in Storyblok. Additional props can also be passed to your component here, if needed.
Finally, add your components to the components
property of the storyblok
config object in astro.config.mjs
. The key is the name of the Blok in Storyblok, and the value is the path to the component relative to src
.
Generating pages
Section titled Generating pagesTo create a route for a specific page
, you can fetch its content directly from the Storyblok API and pass it to the StoryblokComponent
component. Remember to make sure you have added the Page
component to your astro.config.mjs.
Create an index.astro
file in src/pages/
to render the home
page:
To generate pages for all of your blog posts, create a .astro
page that will create dynamic routes. This approach varies depending on whether your routes are prerendered (the default in Astro) or rendered on demand.
Static site generation
Section titled Static site generationIf you are using Astro’s default static site generation, you will use dynamic routes and the getStaticPaths
function to generate your project pages.
Create a new directory src/pages/blog/
and add a new file called [...slug].astro
with the following code:
This file will generate a page for each story, with the slug and content fetched from the Storyblok API.
When adding folders inside of Storyblok, include them in the slug when interacting with the Storyblok API. For example, in the GET request above we can use cdn/stories/blog, with a blog folder inside rather than using them at the root.
On-demand rendering
Section titled On-demand renderingIf you are rendering your routes on demand with an adapter, you will use dynamic routes to fetch the page data from Storyblok.
Create a new directory src/pages/blog/
and add a new file called [...slug].astro
with the following code:
This file will fetch and render the page data from Storyblok that matches the dynamic slug
parameter.
Since you are using a redirect to /404
, create a 404 page in src/pages
:
If the story is not found, the request will be redirected to the 404 page.
Publishing your site
Section titled Publishing your siteTo deploy your website, visit our deployment guides and follow the instructions for your preferred hosting provider.
Rebuild on Storyblok changes
Section titled Rebuild on Storyblok changesIf your project is using Astro’s default static mode, you will need to set up a webhook to trigger a new build when your content changes. If you are using Netlify or Vercel as your hosting provider, you can use its webhook feature to trigger a new build from Storyblok events.
Netlify
Section titled NetlifyTo set up a webhook in Netlify:
-
Go to your site dashboard and click on Build & deploy.
-
Under the Continuous Deployment tab, find the Build hooks section and click on Add build hook.
-
Provide a name for your webhook and select the branch you want to trigger the build on. Click on Save and copy the generated URL.
Vercel
Section titled VercelTo set up a webhook in Vercel:
-
Go to your project dashboard and click on Settings.
-
Under the Git tab, find the Deploy Hooks section.
-
Provide a name for your webhook and the branch you want to trigger the build on. Click Add and copy the generated URL.
Adding a webhook to Storyblok
Section titled Adding a webhook to StoryblokIn your Storyblok space Settings, click on the Webhooks tab. Paste the webhook URL you copied in the Story published & unpublished field and hit Save to create a webhook.
Now, whenever you publish a new story, a new build will be triggered and your blog will be updated.
Official Resources
Section titled Official Resources- Storyblok provides an Astro Integration to add Storyblok to your project.
Community Resources
Section titled Community Resources- Getting the Visual Editor to work for Storyblok + Astro by Sandra Rodgers
- Astro + Storyblok: SSR preview for instant visual editing by Jonas Gierer
- Astro-Storyblok Previews Site with Netlify’s Branch Deploys Feature by Sandra Rodgers