@storyblok/nuxt (Version 10.x)

@storyblok/nuxt is Storyblok’s official development for Nuxt applications.

Requirements

• Nuxt version 4.0 or later
• Node.js LTS (version 22.x recommended)
• Modern web browser (e.g., Chrome, Firefox, Safari, Edge – latest versions)

Installation

Add the package to a project by running this command in the terminal:

npm install @storyblok/nuxt@latest

Usage

Configuration

Import and initialize the SDK using the access token of a Storyblok space.

nuxt.config.ts

import { defineNuxtConfig } from "nuxt";

export default defineNuxtConfig({
  modules: [
    [
      "@storyblok/nuxt",
      {
        accessToken: "YOUR_ACCESS_TOKEN",
        apiOptions: {
          region: "eu",
        },
      },
    ],
  ],
});

Tip

Learn how to retrieve an access token in the access tokens concept.

Caution

The region parameter must be specified unless the space was created in the EU. Learn more in the @storyblok/js reference.

Components

Create a Nuxt component for each block defined in Storyblok. Each component will receive a blok prop, containing the content of the block.

app/storyblok/Feature.vue

<script setup>
  defineProps({ blok: Object });
</script>

<template>
  <div v-editable="blok">
    <h2>{blok.headline}</h2>
  </div>
</template>

Use <StoryblokComponent> to automatically render nested components.

app/storyblok/Page.vue

<script setup>
  defineProps({ blok: Object });
</script>

<template>
  <main>
    <StoryblokComponent v-for="currentBlok in blok.body" :key="currentBlok._uid" :blok="currentBlok" />
  </main>
</template>

Tip

Components created in the storyblok folder are loaded automatically and do not need to be imported.

Fetching and rendering

In a Nuxt page or component, use the one-liner composable useAsyncStoryblok to fetch a story and render the content with the StoryblokComponent element.

app/pages/index.vue

<script setup>
  const { story } = await useAsyncStoryblok("home", {
    // asyncData options https://nuxt.com/docs/4.x/api/composables/use-async-data
    lazy: false,
    api: {
      version: "draft",
      resolve_relations: "featured-articles.posts",
    },
    bridge: {
      resolveRelations: ["featured-articles.posts"],
    },
  });
</script>

<template>
  <StoryblokComponent v-if="story" :blok="story.content" />
</template>

API

storyblok

Import and initialize the SDK to access and configure all features.

import { defineNuxtConfig } from "nuxt";

export default defineNuxtConfig({
  modules: [["@storyblok/nuxt", OPTIONS]],
});

Alternative syntax:

import { defineNuxtConfig } from "nuxt";

export default defineNuxtConfig({
  modules: ["@storyblok/nuxt"],
  storyblok: OPTIONS,
});

All options listed in the @storyblok/vue reference are available. The following additional options are available:

Key	Description	Type
componentsDir	Define a custom directory other than storyblok as the location of components.	string
enableServerMode	Enables the JavaScript client to be used on the Nitro API server (and disables it from being used client-side). Defaults to false.	boolean
enableSudoMode	See example below.	boolean

Example: enableSudoMode

Use it to apply your custom API customizations.

plugins/storyblok.js

import { apiPlugin, StoryblokVue } from "@storyblok/vue";

export default defineNuxtPlugin(({ vueApp }) => {
  vueApp.use(StoryblokVue, {
    accessToken: "<access-token>",
    enableSudoMode: true,
    apiOptions: {
      cache: {
        type: "custom",
        custom: {
          flush() {
            console.log("done");
          },
        },
      },
    },
    use: [apiPlugin],
  });
});

StoryblokVue

Import and use StoryblokVue to create a custom Nuxt plugin as shown in the enableSudoMode example above.

useAsyncStoryblok

Updated in 11.1.4

Using this one-liner composable, enable both data fetching and bridge capabilities. This is the recommended option, as it supports both server-side rendering (SSR) and static site generation (SSG).

<script setup>
  const { story, error } = await useAsyncStoryblok(URL, {
    api: API_OPTIONS,
    bridge: BRIDGE_OPTIONS,
  });

  if (error.value) {
    throw createError({
      statusCode: error.value.statusCode,
      statusMessage: error.value.statusMessage,
    });
  }
</script>

The composable takes the story’s full slug and a single options object. Alongside api and bridge, that object accepts any useAsyncData option, such as lazy or watch, and forwards them to useAsyncData.

bridge is optional. Without it, the bridge still registers and inherits resolveRelations and resolveLinks from the resolve_relations and resolve_links values in api. An explicit bridge value takes precedence over that fallback.

The following example omits bridge and still resolves relations during live preview:

<script setup>
  // The bridge is active and resolves `featured-articles.posts` during live preview.
  const { story } = await useAsyncStoryblok("home", {
    api: {
      version: "draft",
      resolve_relations: "featured-articles.posts",
    },
  });
</script>

For the API_OPTIONS, see the storyblok-js-client reference. For the BRIDGE_OPTIONS, see the @storyblok/preview-bridge reference.

Note

This composable is only available when enableServerClient is set to false (default) in the module configuration.

useStoryblok

Enable both data fetching and bridge capabilities using this composable. Recommended only for client-side rendering (CSR).

<script setup>
  import {useStoryblok} from '@storyblok/vue';
  const {(story, fetchState)} = await useStoryblok(URL, API_OPTIONS, BRIDGE_OPTIONS);
</script>

For the API_OPTIONS, see the storyblok-js-client reference. For the BRIDGE_OPTIONS, see the @storyblok/preview-bridge reference.

Note

This composable is only available when enableServerClient is set to false (default) in the module configuration.

useStoryblokApi

useStoryblokApi() returns the client instantiated in the application.

<script setup>
  import { useStoryblokApi } from "@storyblok/nuxt";
  const storyblokApi = useStoryblokApi();
  const { data } = await storyblokApi.get(URL, API_OPTIONS);
</script>

For the API_OPTIONS, see the storyblok-js-client reference.

Note

This composable is only available when enableServerClient is set to false (default) in the module configuration.

serverStoryblokClient

Get an instance of the Storyblok client for Nitro API Server endpoints with the explicit import #storyblok/server.

server/api/example.ts

import { serverStoryblokClient } from "#storyblok/server";

export default defineEventHandler(async (event) => {
  const storyblokApi = serverStoryblokClient(event);

  const { data } = await storyblokApi.get("cdn/stories/home", {
    version: "draft",
  });

  return { story: data.story };
});

Note

serverStoryblokClient is only available when enableServerClient is set to true in the module configuration.

useStoryblokBridge

useStoryblokBridge() activates the Storyblok Bridge.

<script setup>
  import { useStoryblokApi, useStoryblokBridge } from "@storyblok/nuxt";

  const storyblokApi = useStoryblokApi();
  const { data } = await storyblokApi.get(URL, API_OPTIONS);

  onMounted(() => {
    useStoryblokBridge(STORY_ID, CALLBACK, BRIDGE_OPTIONS);
  });
</script>

For the BRIDGE_OPTIONS, see the @storyblok/preview-bridge reference.

StoryblokComponent

This component automatically renders Storyblok blocks for corresponding Vue components registered in the application. It requires a blok property. Any additional passed properties are forwarded to the Vue component.

<StoryblokComponent :blok="story.content" />

Use it to iterate over blocks fields as follows:

<StoryblokComponent v-for="currentBlok in blok.body" :key="currentBlok._uid" :blok="currentBlok" />

v-editable

Use the v-editable directive in components to connect them to the Storyblok Bridge.

<script setup>
  defineProps({ blok: Object });
</script>

<template>
  <section v-editable="blok">
    <h3>{{ blok.name }}</h3>
  </section>
</template>

StoryblokRichText

Used to render a rich text field from a Storyblok story.

<template>
  <StoryblokRichText :document="blok.richtext_field" />
</template>

Refer to the Vue StoryblokRichText documentation for full usage, customization options, and TypeScript support.

The Nuxt SDK supports all features, including:

• components customization
• optimizeImage support
• useStoryblokRichText for programmatic rendering
• splitTableRows and other utilities

Further resources

Repository PlaygroundSee the repository playground for additional examples.

Nuxt GuideSee the Nuxt guide for a comprehensive walkthrough on integrating Storyblok with Nuxt.

Space Blueprint: NuxtSee the core space blueprint for Nuxt to kickstart a new project.

Previous versions

@storyblok/nuxt (Version 9.x)

@storyblok/nuxt (Version 8.x)

@storyblok/nuxt (Version 7.x)