@storyblok/astro

Installation

Install @storyblok/astro:

npm install @storyblok/astro
# yarn add @storyblok/astro
# See below for pnpm

With pnpm, hoist Storyblok dependencies publicly with .npmrc. For more information, check pnpm documentation on here.

Add the following code to astro.config.mjs and replace the accessToken with the preview API token of your Storyblok space.

astro.config.mjs

import { defineConfig } from "astro/config";
import storyblok from "@storyblok/astro";

export default defineConfig({
  integrations: [
    storyblok({
      accessToken: "<your-access-token>",
    }),
  ],
});

This SDK uses the Fetch API under the hood. If your environment doesn't support it, you need to install a polyfill like isomorphic-fetch. More info on storyblok-js-client docs.

Options

When you initialize the integration, you can pass all @storyblok/js options.

// Defaults
storyblok({
  accessToken: "<your-access-token>",
  bridge: true,
  apiOptions: {}, // storyblok-js-client options
  components: {},
  componentsDir: "src",
  enableFallbackComponent: false,
  customFallbackComponent: "",
  useCustomApi: false,
});

By default, the apiPlugin from @storyblok/js is loaded. If you want to use your own method to fetch data from Storyblok, you can disable this behavior by setting useCustomApi to true, resulting in an optimized final bundle.

Region parameter

Possible values:

eu (default): For spaces created in the EU
us: For spaces created in the US
ca: For spaces created in Canada
ap: For spaces created in Australia
cn: For spaces created in China

Full example for a space created in the US:

storyblok({
  accessToken: "<your-access-token>",
  apiOptions: {
    region: "us",
  },
});

For spaces created in the United States or China, the region parameter must be specified.

Getting started

1

Creating and linking your components to the Storyblok Visual Editor
In order to link your Astro components to their equivalents you created in Storyblok:
First, you need to load them globally by specifying their name and their path in astro.config.mjs:

components: { page: "storyblok/Page", feature: "storyblok/Feature", grid: "storyblok/Grid", teaser: "storyblok/Teaser", },

The src folder is automatically added to the beginning of the path, so in this example your Astro components should be located here:
src/storyblok/Page.astro
src/storyblok/Feature.astro
src/storyblok/Grid.astro
src/storyblok/Teaser.astro
You can choose any other folder in the src directory for your Astro components.
If you prefer to use a different folder than src, you can specify one using the componentsDir option:

storyblok({ componentsDir: "app", });

Now, your Storyblok components can be located anywhere in the app folder, e.g. page: "storyblok/Page" for app/storyblok/Page.astro or page: "Page" for app/Page.astro.

For each component, use the storyblokEditable() function on its root element, passing the blok property that they receive:

--- import { storyblokEditable } from "@storyblok/astro"; const { blok } = Astro.props --- <div {...storyblokEditable(blok)}> <h2>{blok.headline}</h2> </div>

Finally, you can use the provided <StoryblokComponent> for nested components; it will automatically render them (if they have been registered globally beforehand):

--- 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>

The blok is the actual blok data coming from Storyblok's Content Delivery API.

Using fallback components
By default, @storyblok/astro throws an error if a component is not implemented. Setting enableFallbackComponent to true bypasses that behavior, rendering a fallback component in the frontend instead. You can also use a custom fallback component by (for example) setting customFallbackComponent: "storyblok/MyCustomFallback".

Using partial hydration
If you want to use partial hydration with any of the frameworks supported by Astro, follow these steps:
Install the official Astro integration for your desired framework
Create an Astro component that serves as a wrapper and utilizes the most suitable client directive
Create the actual component in Vue, Svelte, React or any other supported framework
For working examples, please refer to the Live Demo on Stackblitz.

Getting Storyblok Stories and using the Storyblok Bridge

Fetching one Story

Use the useStoryblokApi function to have access to an instance of storyblok-js-client:

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

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

const story = data.story;
---

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