Introducing Custom Payload Support for Astro Live Preview (Alpha)

We’re introducing persistent server-side data support for Astro live preview, now available in the latest alpha release.

This improves live preview performance considerably by allowing server-side data to persist across preview updates instead of refetching the full page every time.

What’s new

Persistent server data

Embed sanitized server-side data once and reuse it during live preview updates.

---
import StoryblokServerData from '@storyblok/astro/StoryblokServerData.astro';
const users = await getUsers();
---
<StoryblokServerData users={users} />

One of the main limitations of SSR live preview is that any external API calls or server-side fetches are re-executed on every content change, even if they are unrelated to Storyblok content itself. For example, when fetching data from a third-party API, or when loading a Storyblok configuration story for global site concerns like the header, footer, or theme colors.

This often results in sluggish preview updates and unnecessary delays.

With StoryblokServerData, you can provide this data once so that during live editing, it is reused instead of being fetched again.

getPayload API

A new opt-in API that returns both story data and persistent server data.

const { story, serverData } = await getPayload({ locals: Astro.locals });

This API complements StoryblokServerData. It is similar to the existing getLiveStory function, but additionally returns server data and includes built-in type safety for a better developer experience.

Granular live preview control

Disable live preview on a per-route basis:

<meta name="storyblok-live-preview" content="disabled" />

You can also intercept and control updates via browser events:

document.addEventListener('storyblok-live-preview-updating', (event) => {
  event.preventDefault();
});

Previously, live preview was an all-or-nothing feature. With these controls, you can now selectively enable or disable it per route and take full control over how and when updates are applied.

Preserve component state

You can now prevent specific parts of the UI from re-rendering when live preview updates occur.

<div data-preserve-state></div>

This is useful in less common but important scenarios. For example, if you render a helper widget or tool for content editors inside the page, the current live preview behavior would replace it on every update. By adding this attribute, that section of the DOM is ignored during re-rendering and its state is preserved.

Try it and share feedback

Install the alpha release:

npm i @storyblok/astro@7.4.0-alpha.0

Example usage:

---
import { getPayload } from '@storyblok/astro';
import { storyblokApi } from '@storyblok/astro/client';
import BaseLayout from '@shared/components/BaseLayout.astro';
import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro';
import StoryblokServerData from '@storyblok/astro/StoryblokServerData.astro';
import { getUsers, type User } from 'src/lib/getUsers';
import SomeReactWidget from '../components/SomeReactWidget';
import type { MyStory } from './types';

interface ServerData {
  users?: User[];
}

const { slug } = Astro.params;
const payload = await getPayload<ServerData, MyStory>({ locals: Astro.locals });

const story =
  payload?.story ??
  (
    await storyblokApi.get(`cdn/stories/${slug || 'home'}`, {
      version: 'draft',
    })
  ).data.story;

const users = payload?.serverData?.users ?? (await getUsers());
const disableLivePreview = ['test', 'about-us', 'contact'].includes(slug);
---

<BaseLayout>
  {disableLivePreview && (
    <meta name="storyblok-live-preview" content="disabled" />
  )}
  <p>{users?.length} users loaded.</p>
  <StoryblokComponent blok={story.content} />
  <div data-preserve-state>
    <SomeReactWidget client:load />
  </div>
</BaseLayout>

<StoryblokServerData users={users} />

This is an alpha release. We encourage you to test it in real projects and share feedback before we move toward a stable release.