Add a headless CMS to Astro in 5 minutes

In this tutorial, we’ll learn how to retrieve and display data from the Storyblok API in Astro in order to create a highly performant website with one of the most modern static site generators that exist.

Before moving on, if you’re unfamiliar with the concept of a Headless CMS or Storyblok in particular, you may consult the Storyblok Guide.

Environment Setup

Requirements

In order to follow this tutorial, please make sure you meet these requirements:

• Basic understanding of HTML and JavaScript
• Node.js LTS version installed
• An account in the Storyblok App

Create an Astro project

Let’s create a new Astro project by running the following command:

        
      npm create astro@latest
    

The wizard will guide us through the installation process. For this tutorial, we want to choose the following options:

• Where should we create your new project? Choose your desired project folder.
• How would you like to start your new project? Empty
• Install dependencies? Yes
• Do you plan to write TypeScript? No
• Initialize a new git repository? Up to you!

After the installation has completed, you can go to the project folder and run npm run dev to start the development server.

Adding TailwindCSS

For the styling of our Astro website, we are going to employ Tailwind CSS. Luckily, adding Tailwind to Astro is a breeze.

All you have to run is the following command:

        
      npx astro add tailwindcss
    

And that's it!

Enabling the Visual Editor

In order to see your website in the Storyblok Visual Editor, the default environment URL has to be configured accordingly. To achieve that, simply go to Settings {1} > Visual Editor {2} and the Location {3} field to https://localhost:3000/:

Having done that, you can now go back to the Home story. However, you’ll notice that you won’t see the welcome screen of your Astro project yet.

Just one more step to go: open the Entry configuration {1} and set the Real path to / {2}. Save the story and you’ll see the default screen of your Astro project in the Visual Editor.

Connecting Astro to Storyblok

First of all, we’ll have to install @storyblok/astro, the official SDK to interact with the Storyblok API.

Let’s add it to our project by running:

        
      npm install @storyblok/astro
    

In order to access the data from your newly created space, you need to get your unique API token, which can be found in Settings {1} > Access tokens {2}. Here you can copy the Preview token {3} that's been generated for you.

You can store your preview access token in an .env file in your project root like this:

        
      STORYBLOK_TOKEN=YOUR_PREVIEW_TOKEN
    

In order to use environment variables in Astro, we quickly need to install Vite as a dependency:

        
      npm install vite
    

Now we can use the token and initialize the Storyblok integration in astro.config.mjs:

        
      import { defineConfig } from 'astro/config'
import storyblok from '@storyblok/astro'
import { loadEnv } from 'vite'
import tailwind from "@astrojs/tailwind"
import basicSsl from '@vitejs/plugin-basic-ssl'
const env = loadEnv("", process.cwd(), 'STORYBLOK')

export default defineConfig({
  integrations: [
    storyblok({
      accessToken: env.STORYBLOK_TOKEN,
    }),
    tailwind()
  ],
  vite: {
    plugins: [basicSsl()],
    server: {
      https: true,
    },
  },
})
    

Creating a layout and an index page

Let’s use the useStoryblokApi function we just created to fetch the data of the Home story. Simply replace the existing src/pages/index.astro file with the following code:

        
      ---
import { useStoryblokApi } from '@storyblok/astro'
import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro'
import BaseLayout from '../layouts/BaseLayout.astro'

const storyblokApi = useStoryblokApi()
const { data } = await storyblokApi.get('cdn/stories/home', {
  version: 'draft',
})

const story = data.story
---

<BaseLayout>
  <StoryblokComponent blok={story.content} />
</BaseLayout>
    

As you can see, a component called StoryblokComponent is imported from the SDK. This component is used to dynamically resolve all of the components that exist in our Storyblok space. Let’s take a closer look at this in the next step.

Moreover, we utilize a layout component. Let’s create it:

        
      <html lang='en'>
  <head>
    <meta charset='UTF-8' />
    <meta name='viewport' content='width=device-width' />
    <link rel='icon' type='image/x-icon' href='/favicon.ico' />
    <title>@storyblok/astro</title>
  </head>
  <body class='container mx-auto'>
    <slot />
  </body>
</html>
    

Rendering the Storyblok components

When you create a new Storyblok space and choose to start from scratch, the following four components are created automatically for you:

• page: Content type block
• grid: Nestable block
• feature: Nestable block
• teaser: Nestable block

You can find all of these in the Block Library of your space.

In order to provide the frontend counterparts for these components in our Astro project, we, first of all, need to register them properly in the Storyblok integration. Let's change astro.config.mjs accordingly:

        
      storyblok({
  accessToken: env.STORYBLOK_TOKEN,
+  components: {
+    page: 'storyblok/Page',
+    feature: 'storyblok/Feature',
+    grid: 'storyblok/Grid',
+    teaser: 'storyblok/Teaser',
+  },
})
    

As it is impossible to know in advance which nestable components or bloks will need to be rendered to display our story, StoryblokComponent.astro provided by @storyblok/astro loads the required components based on their technical name.

Having completed this step, we can now create the actual components and display the information that is being passed on in the blok property object.

        
      ---
import { storyblokEditable } from '@storyblok/astro'
import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro'

const { blok } = Astro.props
---

<main {...storyblokEditable(blok)}>
  {
    blok.body?.map((blok) => {
      return <StoryblokComponent blok={blok} />
    })
  }
</main>
    

        
      ---
import { storyblokEditable } from '@storyblok/astro'
import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro'

const { blok } = Astro.props
---

<div {...storyblokEditable(blok)}>
  <div
    class='container mx-auto grid md:grid-cols-3 gap-12 my-12 place-items-center'
  >
    {
      blok.columns?.map((blok) => {
        return <StoryblokComponent blok={blok} />
      })
    }
  </div>
</div>

    

As you can see, both Page.astro and Grid.astro utilize StoryblokComponent.astro to render any nested blocks in the body or columns fields respectively.

        
      ---
import { storyblokEditable } from '@storyblok/astro'

const { blok } = Astro.props
---

<div {...storyblokEditable(blok)}>
  <h3 class='py-32 text-6xl text-[#50b0ae] font-bold text-center'>
    {blok.headline}
  </h3>
</div>
    

        
      ---
import { storyblokEditable } from '@storyblok/astro'

const { blok } = Astro.props
---

<div
  {...storyblokEditable(blok)}
  class='w-full p-12 bg-[#f7f6fd] rounded-[5px] text-center'
>
  <h3 class='text-2xl text-[#1d243d] font-bold'>{blok.name}</h3>
</div>
    

Finally, after having created all of these, you can launch your development server again by running npm run dev. Now, if you go to the Home story in your Storyblok space, you should see your Teaser, Grid, and Feature components being rendered:

Limitations of using the Storyblok Bridge with Astro

Since one of the core ideas of Astro is to ship less JavaScript, its native components are not reactive. Therefore, real-time editing in the Storyblok Visual Editor as you may know from using Storyblok with a framework like Next.js won’t be possible.

However, what we can do is enable the functionality that clicking on components immediately shows the related content fields. Additionally, we can trigger a reload of our Astro frontend whenever the Save button in Storyblok is used.

Wrapping Up

Congratulations! You have successfully integrated your Astro project with Storyblok, resulting in a lightning-fast static site with a phenomenal editing experience.