Introducing @storyblok/nuxt v9 with full Nuxt 4 Support

Developers January 14, 2026

Storyblok is the first headless CMS that works for developers & marketers alike.

We're excited to announce @storyblok/nuxt v9, a major release that brings full compatibility with Nuxt 4 while maintaining backward compatibility with Nuxt 3.15+.

What's new

This release addresses several breaking changes introduced in Nuxt 4 ensuring your Storyblok integration works seamlessly:

Fixed Visual Editor Bridge (#210), now live preview updates now work correctly with Nuxt 4's new shallowRef data handling.
Updated Type Definitions to align them with the Nuxt 4's data fetching changes (null → undefined).
Directory structure support to make use of Nuxt 4's new app/ directory structure.

Learn:

Check out the Nuxt v4 migration notes to know all details on moving a project from v3 to v4.

Migration notes

Update Storyblok components directory

With Nuxt 4's new folder structure, the default srcDir changed from the root folder of the project to to app.

This affects where you place your Storyblok components:

Nuxt Version	Components Location
Nuxt 3	`<root>/storyblok/`
Nuxt 4 (new structure)	`<root>/app/storyblok/`

Handle new useAsyncStoryblok Return Types

The error and data refs have updated types to support both Nuxt 3 and Nuxt 4:

Nuxt Version	`data` when not loaded	`error` when no error
Nuxt 3	`null`	`null`
Nuxt 4	`undefined`	`undefined`

We recommended using truthiness checks for compatibility with both versions:

// Works with both Nuxt 3 and Nuxt 4.
const { data, error } = await useAsyncStoryblok('home', { version: 'draft' });

if (error.value) {
  // Handle error - works whether error.value is null or undefined when no error.
}

if (data.value) {
  // Use data - works whether data.value is null or undefined when loading.
}

Avoid strict equality checks:

// Avoid - only works with Nuxt 3.
if (error.value !== null) { /* ... */ }

// Avoid - only works with Nuxt 4.
if (error.value !== undefined) { /* ... */ }

// Recommended - works with both.
if (error.value) { /* ... */ }

Migration guide

Step 1: Update the Package

# npm
npm install @storyblok/nuxt@latest

# pnpm
pnpm install @storyblok/nuxt@latest

# yarn
yarn add @storyblok/nuxt@latest

Step 2: Enable Nuxt 4 compatibility mode

If you're still on Nuxt 3.15+ but want to adopt Nuxt 4 behaviors (recommended for gradual migration), add the future flag:

nuxt.config.ts

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4,
  },
  compatibilityDate: '2026-01-10',
  // ... rest of your config
});

Hint:

If you're already on Nuxt 4.x, skip this step — these behaviors are the default and this flag is unnecessary.

Step 3: Move Storyblok components

If you're adopting Nuxt 4's new app directory structure:

# Create the new directory
mkdir -p app/storyblok

# Move your components
mv storyblok/* app/storyblok/

Your new structure should look like:

your-project/
├── app/
│   ├── components/
│   ├── pages/
│   ├── storyblok/ # Storyblok components here
│   │   ├── Page.vue
│   │   ├── Teaser.vue
│   │   └── ...
│   └── app.vue
├── server/
├── public/
└── nuxt.config.ts

You also have the option to maintain backward compatibility and keep your Storyblok components at the project root (e.g., to avoid changes during migration):

nuxt.config.ts

export default defineNuxtConfig({
  storyblok: {
    componentsDir: '~~/storyblok', // ~~ always resolves to rootDir
  },
});

Step 4: Update null checks

For compatibility with both v3 and v4 versions of Nuxt, update strict null checks to the following:

// Update these patterns for compatibility with both Nuxt 3 and Nuxt 4:
if (error.value === null) → if (!error.value)
if (error.value !== null) → if (error.value)
if (data.value === null) → if (!data.value)
if (data.value !== null) → if (data.value)

Optional, only needed when targeting one Nuxt version, but recommended for future-proofing.