Visual Preview in Astro

Enhance your editorial and development experience by connecting your local project with Storyblok’s visual editor.

Set the default environment

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

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 { storyblok } from "@storyblok/astro";
import { loadEnv } from "vite";
const env = loadEnv("", process.cwd(), "STORYBLOK");
const { STORYBLOK_DELIVERY_API_TOKEN} = loadEnv(import.meta.env.MODE, process.cwd(), "");
import mkcert from 'vite-plugin-mkcert'

export default defineConfig({
  integrations: [
    storyblok({
      accessToken: env.STORYBLOK_DELIVERY_API_TOKEN,
      apiOptions: {
        region: "eu", // Choose the correct region from your Space.
      },
    }),
  ],
  output: 'server',
  vite: {
    plugins: [ mkcert() ]
  },
});

Restart the dev 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

Connect Astro components with their Storyblok counterparts via the storyblokEditable module.

---
const { blok } = Astro.props
---

<div class="feature" {...storyblokEditable(blok)}>
<div class="feature">
 <span>{blok.name}</span>
</div>

Now, click on a component and see its corresponding block open up in the editor.

Enable live preview in the Visual Editor

By default, live preview in @storyblok/astro is disabled. To enable live preview, set livePreview to true in the astro.config.mjs file.

export default defineConfig({
 integrations: [
   storyblok({
     accessToken: env.STORYBLOK_DELIVERY_API_TOKEN,
     livePreview: true,
     // other options
   }),
 ],
});

In src/pages/index.astro file, replace the existing Astro code with the following.

---
import { useStoryblokApi, getPayload } from "@storyblok/astro";
import StoryblokComponent from "@storyblok/astro/StoryblokComponent.astro";
import Layout from "../layouts/Layout.astro";

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

const storyblokApi = useStoryblokApi();

// Use live preview data or fallback to API
const story =
  payload?.story ??
  (
    await storyblokApi.get("cdn/stories/home", {
      version: "draft",
    })
  ).data.story;
---

<Layout>
  <StoryblokComponent blok={story.content} />
</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 does not exist, it falls back to the Content Delivery API and fetches the home story in draft version. The StoryblokComponent dynamically renders each component defined in the home story.

Deploy the preview environment

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

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