> **Version 11 (alpha)** — **React** / **TypeScript** > Also available: - `?codeOnly=true` for code snippets only - other versions: Version 10.6 (latest) (`/docs/addons/addon-migration-guide.md`), Version 9 (`/docs/9/addons/addon-migration-guide.md`), Version 8 (`/docs/8/addons/addon-migration-guide.md`) # 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](https://storybook.js.org/docs/10/addons/addon-migration-guide.md). We also have a general [Storybook migration guide](https://storybook.js.org/docs/11/releases/migration-guide.md) 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. ```jsonc title="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: ```jsonc title="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](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#nodejs-2212-or-higher) for environment updates and prerelease support. Update the types package in your `package.json` to `^22.12.0`. ```diff title="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: ```diff title=".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`. ```diff title="tsconfig.json" "target": "esnext", "allowJs": true, ... "lib": ["esnext", "dom", "dom.iterable"], - "baseUrl": ".", "rootDir": "." ``` ### CSF Next support [CSF Next](https://storybook.js.org/docs/api/csf/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: ```diff title="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: ````md title="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) 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](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#top-level-setconfig-layout-and-ui-options-removed) for an example and automigration instructions. #### Internal API changes If your addon imports internal Storybook APIs, review these additional changes: - [Removed WebSocket heartbeat controls](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#internal-websocket-heartbeat-controls-removed) - [Removed Vitest workspace configuration helper](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#vitest-addon-requires-vitest-40-or-higher) - [Toolset telemetry returned with the outcome](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#internal-toolset-telemetry-now-returns-with-the-outcome) #### 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](https://github.com/storybookjs/storybook/issues/35513). 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](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#api-and-component-changes) 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: ```diff - 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: ```diff title=".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](https://storybook.js.org/docs/api/csf/csf-next) (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](https://docs.npmjs.com/trusted-publishers) 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: ```diff title=".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](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-10x-to-1100) file. ## Migration example For a complete example of an addon updated to support Storybook 11.0, refer to the [Addon Kit migration PR](https://github.com/storybookjs/addon-kit/pull/94). 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](https://github.com/storybookjs/storybook/discussions/new?category=migrations) in our GitHub repository or come talk to us in our [dedicated addon developer channel, `#addons`](https://discord.gg/KKXFQy9sFc) on Discord.