@storyblok/astro

@storyblok/astro is Storyblok's official development for Astro applications.

Practical resources

• Astro Guide

  See the Astro guide for a comprehensive walkthrough on integrating Storyblok with Astro.

• Space Blueprint: Astro Opens in new tab

  See the blank space blueprint for Astro to kickstart a new project.

Requirements

• Astro version 3.0 or later
• Node.js LTS (version 22.x recommended)
• Modern web browser (e.g., Chrome, Firefox, Safari, Edge – latest versions)

Installation

Add the package to a project by running this command in the terminal:

npm install @storyblok/astro@latest

Usage

Configuration

Import and initialize the SDK using the access token of a Storyblok space.

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

export default defineConfig({
	integrations: [
		storyblok({
			accessToken: 'YOUR_ACCESS_TOKEN',
			apiOptions: {
				region: 'eu',
			},
			components: {
				page: 'storyblok/Page',
				feature: 'storyblok/Feature',
			},
		}),
	],
});

Components

Create an Astro component for each block defined in Storyblok and registered in the configuration. Each component will receive a blok prop, containing the content of the block.

---
import { storyblokEditable } from "@storyblok/astro";

const { blok } = Astro.props
---

<div {...storyblokEditable(blok)}>
  <h2>{blok.headline}</h2>
</div>

Use <StoryblokComponent> to automatically render nested components (provided they are registered globally).

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

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

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

Fetching and rendering

In an Astro page or component, use the client to fetch a story and render the content using StoryblokComponent.

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

const sbApi = useStoryblokApi();
const { data } = await sbApi.get("cdn/stories/home", {
  version: "draft",
  resolve_relations: ["featured-articles.posts"],
});

const story = data.story;
---

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

API

storyblok

Import and initialize the SDK to access and configure all features.

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

export default defineConfig({
	integrations: [
		storyblok(OPTIONS),
	],
});

All options listed in the @storyblok/js package reference are available. The following additional options are available:

Example: components

Register components as follows. The key represents the technical name of the Storyblok block, the value represents the location of the Astro component. The src folder is prepended, the .astro file extension is appended.

storyblok({
	components: {
		page: 'storyblok/Page',
		feature: 'storyblok/Feature',
		grid: 'storyblok/Grid',
		teaser: 'storyblok/Teaser',
	},
});

Example: customFallbackComponent

storyblok({
	enableFallbackComponent: true,
	customFallbackComponent: 'storyblok/MyCustomFallback',
});

Example: bridge

Learn more in the StoryblokBridge reference. Note that resolveRelations and resolveLinks only become effective when livePreview is enabled.

storyblok({
	bridge: {
		customParent?: string,
		preventClicks?: boolean, // Defaults to false.
		resolveRelations?: strings[],
		resolveLinks?: string
	},
});

useStoryblokApi

useStoryblokApi() returns the client instantiated in the application.

---
import { useStoryblokApi } from '@storyblok/astro';

const storyblokApi = useStoryblokApi();
const { data } = await storyblokApi.get(URL, API_OPTIONS);
---

For the API_OPTIONS, see the storyblok-js-client package reference.

getLiveStory

This function returns the updated story object whenever changes are made in the Storyblok Visual Editor, providing a real-time editing experience. Requires livePreview to be enabled.

await getLiveStory(Astro);

Example: getLiveStory

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

const { slug } = Astro.params;
let story = null;

const liveStory = await getLiveStory(Astro);
if (liveStory) {
  story = liveStory;
} else {
  const storyblokApi = useStoryblokApi();
  const { data } = await storyblokApi.get(`cdn/stories/${slug || 'home'}`, {
    version: 'draft',
    resolve_relations: ['featured-articles.posts'],
  });
  story = data?.story;
}
---

<StoryblokComponent blok={story.content} />

storyblok-live-preview-updated

Event to be used to trigger a callback function whenever the DOM has been updated in live preview mode.

<script>
document.addEventListener('storyblok-live-preview-updated', () => {
  console.log('Storyblok live preview: DOM updated');
});
</script>

StoryblokComponent

This component automatically renders Storyblok blocks for corresponding Astro components registered using the components option of the storyblok Astro integration. It requires a blok property. Any additional passed properties are forwarded to the Astro component.

<StoryblokComponent blok={story.content} />

Use it to iterate over blocks fields as follows:

{
	blok.nested_bloks?.map((currentBlok) => (
		<StoryblokComponent blok={currentBlok} />
	));
}

storyblokEditable

This function connects Astri components to their Storyblok counterparts, adding HTML attributes that allow the Storyblok Bridge to work. See the @storyblok/js package reference for further details.

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

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

<section {...storyblokEditable(blok)}>
	{blok.title}
</section>

renderRichText

This function converts a Storyblok rich text field into HTML.

---
import { renderRichText } from "@storyblok/astro";

const { blok } = Astro.props;
const renderedRichText = renderRichText(blok.richtext_field);
---

<div set:html={renderedRichText} />

See the @storyblok/richtext package reference for further details.

Further resources

• Repository Playground Opens in new tab

  See the repository playground for additional examples.

• storyblok-rich-text-astro-renderer by NordSecurity Opens in new tab

  Rich text renderer package for advanced functionality, including the rendering of native Astro components for nested rich text blocks.