91,045
Get Started
Docs
Storybook Docs

Addon migration guide for Storybook 11.0

We sincerely appreciate the dedication and effort addon creators put into keeping the Storybook ecosystem vibrant and up-to-date. As Storybook evolves to version 11.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 10.x to 11.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the Addon migration guide for Storybook 10.0.

We also have a general Storybook migration guide that covers updates to your Storybook instance rather than your addon code.

Use this prompt with your AI assistant to migrate your addon.

Dependency updates

You will need to update your Storybook dependencies. Peer dependencies must point to ^11.0.0 to ensure broad compatibility for your end users. Development dependencies can be set to ^11.0.0, or to next if you want to try the latest prerelease all year round.

package.json
{
  "devDependencies": {
    "@storybook/addon-docs": "next",
    "@storybook/react-vite": "next",
    "storybook": "next",
  },
  "peerDependencies": {
    "storybook": "^11.0.0",
  },
}

Supporting earlier versions

If your addon supports multiple major versions of Storybook, you can specify a wider version range in your peer dependencies:

package.json
{
  "name": "your-storybook-addon",
  "peerDependencies": {
    "storybook": "^10.0.0 || ^11.0.0",
  },
  "devDependencies": {
    "storybook": ">=11.0.0-0 <12.0.0-0", // For local development
  },
}

However, we recommend releasing a new major version of your addon alongside new major versions of Storybook:

  1. It makes it easier to maintain your code
  2. It allows you to take advantage of new features and improvements
  3. It provides a clearer upgrade path for your users

Key changes for addons

Here are the changes in version 11.0 that impact addon development.

Minimum version bumps

Node.js

Storybook 11 targets Node.js 22.12 or higher. See the Node.js migration reference for environment updates and prerelease support. Update the types package in your package.json to ^22.12.0.

package.json
-    "@types/node": "^20",
+    "@types/node": "^22.12.0",

Change your CI to build and test your addon against this version and more recent stable versions. Use the opportunity to improve your workflow security by pinning action versions to specific commit SHAs:

.github/workflows/build.yml
     strategy:
       matrix:
-        node-version: [20.19, 22.12]
+        node-version: [22.12, 24.21]
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
 
       - name: Install pnpm
-        uses: pnpm/action-setup@v4
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0

TypeScript

The minimum supported TypeScript version is now 5. Update your TypeScript dependency and remove deprecated configuration from your tsconfig.json.

tsconfig.json
     "target": "esnext",
     "allowJs": true,
     ...
     "lib": ["esnext", "dom", "dom.iterable"],
-    "baseUrl": ".",
     "rootDir": "."

CSF Next support

CSF Next becomes the default CSF format in Storybook 11. Your users will need your addon to support CSF Next to get type safety benefits. You will need to update your src/index.ts file to export a definePreviewAddon callback. Users will call it in their preview.ts file to register your addon's preview annotations.

If you haven't done so already when porting to Storybook 10, apply the following change:

src/index.ts
- // make it work with --isolatedModules
- export default {};
+ import { definePreviewAddon } from "storybook/internal/csf";
+ import addonAnnotations from "./preview";
+
+ export default () => definePreviewAddon(addonAnnotations);

Make sure to also update your installation instructions to tell users to call that callback in their preview.ts file. Below is an example you can use:

README.md
Register the addon's preview annotations in `.storybook/preview.ts`.
 
```ts
// .storybook/preview.ts
 
// Replace your-framework with the framework you are using (e.g., react-vite, nextjs-vite)
import { definePreview } from '@storybook/your-framework';
 
import myAddon from 'my-addon';
 
export default definePreview({
  // ...rest of preview
  addons: [myAddon()], // 👈 register the addon here
});
```

Addon API changes

Manager layout configuration

Move deprecated top-level addons.setConfig layout options into layout, and move enableShortcuts into ui. The old top-level values are no longer applied. See the setConfig migration reference for an example and automigration instructions.

Internal API changes

If your addon imports internal Storybook APIs, review these additional changes:

Tab UI type removed

The TAB addon UI type has been removed. It was not possible for us to build an accessible keyboard navigation experience in the Storybook toolbar with tabs present in the toolbar.

Addons may now only create PANEL, TOOL or TOOLEXTRA types. We recommend you replace any existing use of this type by a PANEL, or by a TOOL that opens a Modal.

Changes to story index

In the early days of Storybook docs support, unattached docs pages in the story index were wrapped in a fake component entry. This anachronism has survived over the years, and is being fixed in Storybook 11. Unattached MDX pages will now be allowed to be top-level entries in the index, without a component wrapper.

In very rare cases, this can affect addons that parse the index. If relevant to your addon, make sure it continues to correctly identify unattached docs entries in Storybook 11. If you use useStorybookState().index, you are likely to be impacted.

The StoriesHash type has been renamed to IndexHash in previous versions. The legacy StoriesHash type is now removed. Rename any usage of StoriesHash to IndexHash.

Removed components

The storybook/internal/components package has had deprecated components since Storybook 10.1. Those are now removed. You may find a full list of removed components and alternatives in the Storybook 10 section of the Migration.md file.

Icons package imports must be named

The @storybook/icons package has moved from a default barrel file export to named exports in previous versions. The default barrel export will be removed in Storybook 11 or 12.

Review your usage of the @storybook/icons package and ensure you import individual icons via named imports.

useThemeParameters removal

The useThemeParameters hook is removed in Storybook 11. You may instead directly access the theme from the StoryContext object that the hook took as a parameter:

- const { themeOverride } = useThemeParameters(context);
+ const { themeOverride } = context.parameters.themes ?? {};

Optional changes

Port your local Storybook to use CSF Next

You may load your own preview annotations in your local Storybook instance, to test that they work as intended:

.storybook/preview.ts
-import type { Preview } from '@storybook/react-vite';
+import { definePreview } from '@storybook/react-vite';
+import addonDocs from '@storybook/addon-docs';
+import yourOwnAddon from '../dist/index.js';
 
-const preview: Preview = {
+const preview = definePreview({
+  addons: [addonDocs(), yourOwnAddon()],
   parameters: {
     // ...
   },
   initialGlobals: {
     // ...
   },
-};
+});

Change all your stories to use the factory functions (e.g. preview.meta(), meta.story()) and check for any type errors that become visible with CSF Next's type safety.

NPM Trusted Publishing

We strongly recommend you use NPM Trusted Publishing to keep your users secure. You will first need to change your package settings on npmjs.com. Then, in the release workflow, ensure you use Node 24 (minimum supported version for Trusted Publishing) and that you no longer pass a NPM token:

.github/workflows/release.yml
    if: "!contains(github.event.head_commit.message, 'ci skip') && !contains(github.event.head_commit.message, 'skip ci') && github.repository != 'storybookjs/addon-kit'"
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      id-token: write
    steps:
 
-      - name: Use Node.js 20.x
-        uses: actions/setup-node@v4
+      - name: Use Node.js 24.x
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 20.x
+          node-version: 24.x
           cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
 
       - name: Install dependencies
@@ -28,6 +28,5 @@ jobs:
       - name: Create Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           pnpm run release

11.0.0 full migration guide

For a full list of changes, please visit the Migration.md file.

Migration example

For a complete example of an addon updated to support Storybook 11.0, refer to the Addon Kit migration PR. Once merged, it will demonstrate all the necessary and recommended changes for Storybook 11.

Releasing

To support Storybook 11.0, we encourage you to release a new major version of your addon. For experimental features or testing, use the next tag. This allows you to gather feedback before releasing a stable version.

Support

If you're having issues with your addon after following this guide, please open a new discussion in our GitHub repository or come talk to us in our dedicated addon developer channel, #addons on Discord.

Was this page useful?
✍️ Edit on Github