Announcing Live Preview for Storyblok’s Astro Integration

We are absolutely thrilled to announce that starting with version 4.1.0 our Astro integration @storyblok/astro now officially supports the live preview functionality of Storyblok’s beloved Visual Editor. With this new feature, developers can empower editors to create content in Astro projects and benefit from real-time, instantaneous feedback reflecting their changes. Let’s see it in action:

How to Use it

As this is an experimental, opt-in feature, you first of all need to enable it by setting livePreview to true in your astro.config.mjs file.

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

Since the live preview feature depends on the Astro object, we’ve designed a new utility function called useStoryblok that takes it as a parameter. Additionally, you may want to pass Storyblok Bridge Options for a particular page or route as a parameter. Let’s take a look at an example:

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

const { slug } = Astro.params;

const story = await useStoryblok(
  // The slug to fetch
  `cdn/stories/${slug === undefined ? "home" : slug}`,
  // The API options
  {
    version: "draft",
  },
  // The Bridge options (optional, if an empty object, null, or false are set, the API options will be considered automatically as far as applicable)
  {},
  // The Astro object (essential for the live preview functionality)
  Astro
);
---

<StoryblokComponent blok={story.content} />
    

Finally, make sure that your project runs in SSR mode for the live preview functionality to work. For further information, you may want to read our tutorial on how to create a dedicated preview environment for a Storyblok and Astro project.

And that’s it, just like that, you enabled live preview!

How it Originated

When we released the first version of @storyblok/astro in 2022, we were aware that, in direct comparison to the other integrations provided as part of our JavaScript SDK ecosystem, the Astro integration does not offer the benefit of real-time visual feedback. As Astro differs fundamentally from other modern JavaScript frameworks and does not provide a client-side runtime for its native components (which, of course, is part of its allure), the time-proven approach we utilize for other frameworks is not applicable in an Astro context. While we had always envisioned and hoped to be able to introduce support for this integral Storyblok feature, we had concluded that it was not technically feasible.

It took the ingenious effort of one of our closest partners, Virtual Identity, and, in particular, their developer Mario Hamann, to prove us (very!) wrong. Virtual Identity Board Member Timo Mayer and Mario Hamann reached out to us and presented a POC that follows a very creative and masterfully designed approach. In close collaboration, Mario Hamann and our own Dipankar Maikap refined, tested, and integrated this solution. We are truly grateful to Virtual Identity for not only providing this innovative impetus but even going above and beyond to dedicate their time and effort in order to get this market-ready. In any case, we know which super talented team we would turn to again to solve an almost impossible challenge.

How it Works Under The Hood

In a nutshell, this approach works by updating the DOM using the JavaScript replaceWith() method. The DOM is replaced either entirely or partially, depending on the context in which the input event of the Storyblok Bridge is triggered. Thanks to the power and flexibility of Astro’s Integration API, the Astro object can be utilized to store the most up-to-date story data delivered by the Storyblok Bridge. Furthermore, an injected middleware determines whether to load a story normally or update the DOM, taking into account the data stored in the Astro object.

While this method has proven to work incredibly well in the majority of our tests, it is important to point out that you may encounter performance drawbacks in large-scale projects with complex relations to resolve and/or heavy client slide scripts. Hence, we’ve released it as an experimental, opt-in feature for now. If you experience any issues, we’d really appreciate it if you created an issue on GitHub. We rely on your feedback and are more than happy to look into it.

If you want to explore it yourself, the key logic is contained in these files:

• ./lib/live-preview/handleStoryblokMessage.ts
• ./lib/live-preview/middleware.ts`
• ./lib/index.ts

Additionally, Dipankar Maikap, thanks to the support provided by Matthew Phillips, CTO of The Astro Technology Company, has successfully created a Vite virtual module that makes it possible to pass Storyblok Bridge Options from Astro Pages.

Next Steps

We hope you’re excited to try out this new feature! We would absolutely love to see your projects built with Storyblok and Astro, and hear your feedback about this latest feature.

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.