Auto-Resolving Components & Rich Text Upgrades in the Astro SDK

We are thrilled to share that starting with version 7.3.0, our Astro SDK @storyblok/astro includes a few powerful new features.

Keep reading to learn what’s new and how to adopt the new functionality in your existing Storyblok Astro project or even the next build.

No more manual component mapping

With this release, we’ve added support for automatically resolving all Storyblok components. You no longer need to map each component in astro.config.mjs manually.

import { storyblok } from '@storyblok/astro';
export default {
  integrations: [
    storyblok({
      accessToken: 'OsvN....',
      bridge: {
        resolveRelations: ['featured-articles.posts'],
      },
      enableFallbackComponent: true,
      livePreview: true,
     components: {
        teaser: 'components/Teaser.astro',
        grid: 'components/Grid.astro',
        feature: 'components/Feature.astro',
        page: 'components/Page.astro',
      },
    }),
  ],
};

Auto-resolve always looks for a storyblok folder. By default, that’s src/storyblok. If you set the componentsDir to point elsewhere, like src/components, the SDK will detect it at src/components/storyblok.

Your existing code will continue to work, and you can still override the auto-import behavior if needed. For example, you can manually import a component from another location:

components: {
  teaser: 'components/TestTeaser.astro',
},

Render rich text to HTML automatically

This release also introduces an experimental richTextToHTML function that automatically resolves every component and returns HTML.

---
import { richTextToHTML } from '@storyblok/astro/client';
const renderedRichText = await richTextToHTML(blok.text);
---
<Fragment set:html={renderedRichText} />

This feature relies on Astro’s experimental Container API.

Handle live preview events

If you use the live preview feature available in our SDK, you can now listen to preview events in your Astro project. This lets you to create custom UI behaviour, such as showing a spinner while the preview content is loading.

<script>
  const spinner = document.getElementById('spinner');

  document.addEventListener('storyblok-live-preview-updating', (story) => {
    if (spinner) spinner.style.display = 'block'; // show spinner
  });

  document.addEventListener('storyblok-live-preview-updated', (story) => {
    if (spinner) spinner.style.display = 'none'; // hide spinner
  });
</script>

Astro uses SSR, so its live preview isn’t reactive like React or Vue. These events give you more control over the preview experience.

Use the global API instance anywhere

Previously, the useStoryblokApi hook only worked in page contexts. That made it unavailable in API routes or other parts of your Astro project, such as the content layer.

Now you can import a global Storyblok API instance, with full type support, anywhere in your project:

import { storyblokApi } from '@storyblok/astro/client';

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

Developer experience improvements

• StoryblokComponent is now auto-imported with improved type hints.
• Several functions now include JSDoc comments, providing helpful hints and examples directly in your code editor.
• General DX fixes and quality-of-life improvements.

Next steps

Try out the new features in version 7.3.0 and simplify your Storyblok and Astro workflow. We would love to see what you build and hear your feedback.

Want to contribute to @storyblok/astro? Open an issue or submit a pull request in the official GitHub repository.