Integrate Astro with Storyblok

Use Storyblok to manage the content of your Astro website.

Quickstart

The fastest way to get started is using Storyblok’s Core Blueprint or CLI wizard:

Blueprint (UI)
CLI

Use Storyblok’s Core Blueprint to launch an Astro project, complete with a space, GitHub repository, and deployment environment.

Use Storyblok’s CLI to set up a new space and scaffold an Astro project. In the terminal, run:

storyblok create --template astro

Manual setup

Alternatively, set up the project from scratch and configure your frontend code.

This guide has been tested with the following package versions:

astro@5.7.14
storyblok-astro@6.2.0
Node.js v22.13.0

No Storyblok account?Sign up and create a space for free

Create a new space

Log in to Storyblok, select + Add Space → New Space, and follow the steps.
Create an Astro project

Create a new Astro project following the official installation guide.
Install @storyblok/astro

In the terminal, cd into the project, and install the package.
Terminal window
```
npm install @storyblok/astro
```

Next, in the astro.config.mjs file, initialize the Storyblok module:

import { defineConfig } from "astro/config";
import { storyblok } from "@storyblok/astro";
import { loadEnv } from "vite";
const env = loadEnv("", process.cwd(), "STORYBLOK");
const { STORYBLOK_DELIVERY_API_TOKEN } = loadEnv(import.meta.env.MODE, process.cwd(), "");

export default defineConfig({
  integrations: [
    storyblok({
      accessToken: env.STORYBLOK_DELIVERY_API_TOKEN,
      apiOptions: {
        region: "eu",
      },
    }),
  ],
  output: "server",
});

In the root of the project, create a .env file to store the Storyblok access token.

STORYBLOK_DELIVERY_API_TOKEN=<YOUR-ACCESS-TOKEN>

The Storyblok integration makes features like fetching, components registration, and bridge available across your project.

Fetch a single story

In the src/pages/index.astro file, replace Astro’s default contents with the following.

---
import { useStoryblokApi } from "@storyblok/astro";
import StoryblokComponent from "@storyblok/astro/StoryblokComponent.astro";
import Layout from "../layouts/Layout.astro";

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

const { story } = data;
---

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

The StoryblokComponent dynamically renders content type and nestable blocks. In this case, it looks for the content type block of the home story.

Create and register blocks

Create Page.astro component to render all stories of the page content type, such as the home story.

---
import StoryblokComponent from "@storyblok/astro/StoryblokComponent.astro";
const { blok } = Astro.props;
---

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

Using StoryblokComponent iterate through the body field and render the blocks in it.

Stories can have a body field that contains an array of custom type blocks, such as Feature, Teaser, and Grid.

Create the code for these components as follows.

---
const { blok } = Astro.props;
---

<div class="feature">
  <span>{blok.name}<span> </span></span>
</div>

---
const { blok } = Astro.props;
---

<div class="teaser">
  <h2>{blok.headline}</h2>
</div>

---
import StoryblokComponent from "@storyblok/astro/StoryblokComponent.astro";
const { blok } = Astro.props;
---

<div class="grid">
  {
    blok.columns?.map((nestedBlok) => {
      return <StoryblokComponent blok={nestedBlok} />;
    })
  }
</div>

Similar to Page.astro, Grid.astro iterates over the columns block field.

Add these components to the astro.config.mjs file.

import { defineConfig } from "astro/config";
import { storyblok } from "@storyblok/astro";
import { loadEnv } from "vite";
const env = loadEnv("", process.cwd(), "STORYBLOK");const { STORYBLOK_DELIVERY_API_TOKEN} = loadEnv(import.meta.env.MODE, process.cwd(), "");

export default defineConfig({
  integrations: [
    storyblok({
      accessToken: env.STORYBLOK_DELIVERY_API_TOKEN,
      apiOptions: {
        region: "eu", // Optional. Defaults to "eu"
      },
      components: {
        page: "storyblok/Page",
        grid: "storyblok/Grid",
        feature: "storyblok/Feature",
        teaser: "storyblok/Teaser",
      }
    }),
  ],
  output: 'server',
});