Visual Preview in Astro

Enhance your editorial and development experience by connecting your local project with Storyblok’s Visual Editor.

Set the default environment

Open Settings → Visual Editor and set the default environment to the URL of the local development server, for example, Astro’s default https://localhost:4321/.

For Astro, install the vite-plugin-mkcert package.

npm install vite-plugin-mkcert --save-dev

Add the plugin to your Astro config file.

import { defineConfig } from "astro/config";
import mkcert from "vite-plugin-mkcert";

export default defineConfig({
  output: "server",
  vite: {
    plugins: [mkcert()],
  },
});

Restart the development server if necessary.

To render the home story correctly in the Visual Editor, select the Config section and type / in the Real path field.

You may have to open the URL in a separate browser tab and accept the certificate first.

Bridge with the Visual Editor

StoryblokBlock passes an editable prop to every block component. Spread it on the root element of the component to connect it with its Storyblok counterpart.

---
const { block } = Astro.props;
const { block, editable } = Astro.props;
---

<div class="feature">
<div class="feature" {...editable}>
  <span>{block.name}</span>
</div>

Repeat this step for the Page, Grid, and Teaser components.

Next, add the StoryblokPreview component to the src/pages/index.astro file. It loads the Storyblok Bridge, which connects the page to the Visual Editor and reloads it when you save or publish content.

---
import { StoryblokPreview } from "@storyblok/astro";
import { apiClient, StoryblokBlock } from "../storyblok";
import Layout from "../layouts/Layout.astro";

const { data } = await apiClient.stories.get("home", {
  query: { version: "draft" },
});

const story = data?.story;

if (!story) {
  return new Response(null, { status: 404 });
}
---

<Layout>
  <StoryblokBlock block={story.content} />
  <StoryblokPreview />
</Layout>

Now, select a component in the preview and its corresponding block opens up in the editor.

Enable live preview in the Visual Editor

Live preview updates the page while you edit content in the Visual Editor.

While you edit, the Visual Editor sends the unsaved content to the page. To store this content in Astro.locals, create a src/middleware.ts file.

import { sequence } from "astro:middleware";
import { storyblokPreviewMiddleware } from "@storyblok/astro";

export const onRequest = sequence(storyblokPreviewMiddleware);

To use the live preview data, update the src/pages/index.astro file.

---
import { StoryblokPreview } from "@storyblok/astro";
import { getPayload, StoryblokPreview } from "@storyblok/astro";
import { apiClient, StoryblokBlock } from "../storyblok";
import Layout from "../layouts/Layout.astro";

const { data } = await apiClient.stories.get("home", {
  query: { version: "draft" },
});

const story = data?.story;
const payload = await getPayload({ locals: Astro.locals });

// Use live preview data or fall back to the API
const story = payload.story ?? (await apiClient.stories.get("home", { query: { version: "draft" } })).data?.story;

if (!story) {
  return new Response(null, { status: 404 });
}
---

<Layout>
  <StoryblokBlock block={story.content} />
  <StoryblokPreview />
  <StoryblokPreview liveUpdate />
</Layout>

The getPayload function provides access to live preview story data from Astro.locals. If a payload exists, the index page uses the story from the live preview. If a payload doesn’t exist, it falls back to the Content Delivery API and fetches the home story in draft version.

With the liveUpdate property, the StoryblokPreview component also updates the page while you type.

Deploy the preview environment

Make sure to fetch the draft version of the content and use a preview access token. To reflect content updates dynamically upon saving content, deploy in server-side rendering mode.

For the production environment, fetch the published version of the content and use a public access token.

@storyblok/astro Package Reference

Concept: Visual Editor

mkcert Homebrew Formula

mkcert GitHub Repository