Almost EVERYONE who tried headless systems said they saw benefits. Download the state of CMS now!

Storyblok now on AWS Marketplace: Read more

O’Reilly Report: Decoupled Applications and Composable Web Architectures - Download Now

Empower your teams & get a 582% ROI: See Storyblok's CMS in action

Skip to main content

Announcing @storyblok/astro

Developers
Manuel Schröder
Try Storyblok

Storyblok is the first headless CMS that works for developers & marketers alike.

We are very excited to announce the release of @storyblok/astro! Using Storyblok in your Astro project is now much easier and faster than before. Thanks to the powerful Astro Integration API and our new module, you can get up and running in a matter of minutes.

Let's explore how it works!

Live demo:

In a hurry? Head over to the Live Demo on StackBlitz!

Section titled Storyblok/astro Usage Storyblok/astro Usage

First of all, install @storyblok/astro:

        
      npm install @storyblok/astro
# yarn add @storyblok/astro
    

Add the following code to your 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>",
      components: {
        page: "storyblok/Page",
	feature: "storyblok/Feature",
	grid: "storyblok/Grid",
	teaser: "storyblok/Teaser",
      }
    }),
  ],
});
    

As you can see, all components that you defined in Storyblok have to be globally registered through the components object. Henceforth, they’ll be loaded automatically when using StoryblokComponent as shown below.

Section titled Querying the Storyblok API Querying the Storyblok API

In any of your Astro pages, you can now use the useStoryblokApi function to fetch data from Storyblok. In this example, we're retrieving the home Story:

src/pages/index.astro
        
      ---
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}" />
    

Section titled Creating Astro Components Creating Astro Components

For each Astro component that should be linked to its equivalent in your Storyblok Space, you can use the storyblokEditable() function on its root element, passing the blok property that they receive and enabling communication with the Storyblok Bridge. Furthermore, you can use the StoryblokComponent to dynamically load any of the components that you registered globally.

src/storyblok/Page.astro
        
      ---
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>
    

Section titled ...but what about partial hydration? ...but what about partial hydration?

We've got you covered! Being able to bring your favorite framework and benefitting from partial hydration is a huge advantage of using Astro.

If you want to use partial hydration with any of the frameworks supported by Astro, follow these steps:

  1. Install the official Astro integration for your desired framework
  2. Create an Astro component that serves as a wrapper and utilizes the most suitable client directive
  3. Create the actual component in Vue, Svelte, React or any other supported framework

For working examples, you can explore the Live Demo on Stackblitz.

Section titled Enabling the Storyblok Bridge Enabling the Storyblok Bridge

The Storyblok Bridge is automatically activated by default. If you would like to disable it or enable it conditionally (e.g. depending on the environment) you can set the bridge parameter to false in astro.config.mjs.

hint:

Since Astro is not a reactive JavaScript framework and renders everything as HTML, the Storyblok Bridge will not provide real-time editing as you may know it from other frameworks. However, it automatically refreshes the site for you whenever you save or publish a story.

And that’s it! Your Astro project is now fully integrated with the Storyblok CMS.

Have a look at @storyblok/astro for more detailed documentation.

Section titled Next Steps Next Steps

Are you excited to try it out? We would love to see your projects built with Storyblok and Astro!

We are planning to release a complete Storyblok Astro Ultimate Tutorial in which you will learn how to build a feature-rich, multilingual website.

Would you like to contribute to the development of @storyblok/astro? Feel free to create an issue or a PR in the official GitHub repository.

ResourceLink
@storyblok/astro GitHub repositoryhttps://github.com/storyblok/storyblok-astro
@storyblok/astro NPM packagehttps://npmjs.com/package/@storyblok/astro
Storyblok Learning Hubhttps://storyblok.com/docs
DEV.to announcement blog posthttps://dev.to/storyblok/announcing-storyblokastro-44po