---
title: @storyblok/astro (Version 7.x)
description: @storyblok/astro is Storyblok's official development kit for Astro applications.
url: https://storyblok.com/docs/libraries/js/astro-sdk/v7
---

# @storyblok/astro (Version 7.x)

[@storyblok/astro](https://github.com/storyblok/monoblok/tree/main/packages/astro) is Storyblok’s official development for Astro applications.

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

```bash
npm install @storyblok/astro@7
```

## Usage

### Configuration

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

astro.config.mjs

```js
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",
      },
    }),
  ],
});
```

> [!TIP]
> Learn how to retrieve an access token in the [access tokens concept](/docs/concepts/access-tokens).

> [!WARNING]
> The `region` parameter must be specified unless the space was created in the EU. Learn more in the [@storyblok/js reference](/docs/libraries/js/js-sdk).

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

src/storyblok/Feature.astro

```astro
---
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).

src/storyblok/Page.astro

```astro
---
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`.

src/pages/index.astro

```astro
---
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.

```js
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](/docs/libraries/js/js-sdk) are available. The following additional options are available:

| Key | Description | Type |
| --- | --- | --- |
| `bridge` | Enable or disable the Storyblok Bridge. Without livePreview being enabled, the Bridge is configured to refresh on saving and publishing the story. Pass an object with Bridge options for additional configuration. See example below. | `boolean \| object` |
| `components` | Register Astro components intended to render Storyblok blocks. Located in the src directory by default. See example below. | `object` |
| `componentsDir` | Define a custom directory other than src as the location of components. | `string` |
| `livePreview` | Enable or disable live preview. Disabled by default. | `boolean` |
| `enableFallbackComponent` | Enable or disable a fallback component to be rendered if no React component has been defined for a Storyblok block. Disabled by default. | `boolean` |
| `customFallbackComponent` | Register a custom fallback component. Requires enableFallbackComponent to be enabled. See example below. | `string` |
| `useCustomApi` | By default, the apiPlugin from @storyblok/js is loaded. Disable this behavior by setting useCustomApi to true to optimize the final bundle when using a custom method to fetch data from Storyblok. | `boolean` |

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

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

#### Example: `customFallbackComponent`

```js
storyblok({
  enableFallbackComponent: true,
  customFallbackComponent: "storyblok/MyCustomFallback",
});
```

#### Example: `bridge`

Learn more in the [@storyblok/preview-bridge reference](/docs/libraries/js/preview-bridge). Note that `resolveRelations` and `resolveLinks` only become effective when `livePreview` is enabled.

```js
storyblok({
  bridge: {
    customParent: "iframe-container",
    preventClicks: true, // Defaults to false.
    resolveRelations: ["article.author"],
    resolveLinks: "story",
  },
});
```

### `useStoryblokApi`

`useStoryblokApi()` returns the client instantiated in the application.

```astro
---
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 reference](https://github.com/storyblok/monoblok/tree/main/packages/js-client).

### `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.

```js
await getLiveStory(Astro);
```

#### Example: `getLiveStory`

```astro
---
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.

```html
<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.

```jsx
<StoryblokComponent blok={story.content} />
```

Use it to iterate over blocks fields as follows:

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

### `storyblokEditable`

This function connects Astro components to their Storyblok counterparts, adding HTML attributes that allow the Storyblok Bridge to work. See the [@storyblok/js reference](/docs/libraries/js/js-sdk) for further details.

```astro
---
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.

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

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

<div set:html={renderedRichText} />
```

See the [@storyblok/richtext reference](/docs/libraries/js/rich-text) for further details.

## Further resources

[Repository Playground](https://github.com/storyblok/monoblok/tree/main/packages/astro/playground) See the repository playground for additional examples.

[storyblok-rich-text-astro-renderer by NordSecurity](https://github.com/NordSecurity/storyblok-rich-text-astro-renderer) Rich text renderer package for advanced functionality, including the rendering of native Astro components for nested rich text blocks.

[Astro Guide](/docs/guides/astro/) See the Astro guide for a comprehensive walkthrough on integrating Storyblok with Astro.

[Space Blueprint: Astro](https://github.com/storyblok/blueprint-core-astro) See the core space blueprint for Astro to kickstart a new project.