@nx/storybook - Migrations

For an overview of the plugin and setup instructions, see the @nx/storybook introduction.

The @nx/storybook plugin provides various migrations to help you migrate to newer versions of storybook projects within your Nx workspace. Below is a complete reference for all available migrations.

24.0.x

remove-deprecated-executors

Version: 24.0.0-beta.3

Converts targets using the removed @nx/storybook executors to inferred tasks; an AI prompt finishes the targets the converter cannot convert safely and validates the project graph.

Convert @nx/storybook build and serve targets to inferred tasks

Nx 24 removes the @nx/storybook:storybook and @nx/storybook:build executors and their @nrwl aliases. The migration registers @nx/storybook/plugin in nx.json and converts the targets that use those executors to inferred tasks. It moves settings such as docsMode and staticDir into .storybook/main.*. A target with nothing left to override is removed from project configuration. When several projects share the same remaining options, those options move to a targetDefaults entry scoped to the plugin. targetDefaults entries keyed by a removed executor are removed once no target uses that executor.

The migration lists the targets the converter cannot convert safely. In agentic runs, an AI prompt finishes them and validates the project graph.

Sample code changes

Before

apps/app1/project.json

{
  "name": "app1",
  "targets": {
    "build-storybook": {
      "executor": "@nx/storybook:build",
      "outputs": ["{options.outputDir}"],
      "options": {
        "configDir": "apps/app1/.storybook",
        "outputDir": "dist/storybook/apps/app1"
      },
      "configurations": {}
    },
    "storybook": {
      "executor": "@nx/storybook:storybook",
      "options": {
        "port": 4400,
        "configDir": "apps/app1/.storybook"
      },
      "configurations": {
        "ci": {
          "quiet": true
        }
      }
    }
  }
}

After

apps/app1/project.json

{
  "name": "app1",
  "targets": {
    "build-storybook": {
      "options": {
        "config-dir": ".storybook",
        "output-dir": "../../dist/storybook/apps/app1"
      }
    },
    "storybook": {
      "configurations": {
        "ci": {
          "args": ["--quiet"]
        }
      },
      "options": {
        "config-dir": ".storybook",
        "port": 4400
      }
    }
  }
}

nx.json

{
  "plugins": [
    {
      "plugin": "@nx/storybook/plugin",
      "options": {
        "buildStorybookTargetName": "build-storybook",
        "serveStorybookTargetName": "storybook",
        "staticStorybookTargetName": "static-storybook",
        "testStorybookTargetName": "test-storybook"
      }
    }
  ]
}

update-24-0-0-add-start-storybook-ready-when

Version: 24.0.0-beta.5

Sets a readyWhen that waits for the Storybook port on @storybook/angular:start-storybook targets that get no readyWhen from their own configuration or targetDefaults, so tasks that depend on them with waitFor: 'ready' start once Storybook is listening. Also sets continuous: true on those targets when neither they nor targetDefaults set continuous and they don’t set smokeTest.

Wait for Angular Storybook targets to listen

The @storybook/angular:start-storybook builder does not tell Nx when Storybook is listening. This migration sets a readyWhen on these targets that waits until Storybook accepts connections on its port. Tasks that depend on such a target with waitFor: 'ready' then start once Storybook is listening, instead of as soon as the target starts.

The readyWhen reads the port and host the way the builder does. A non-empty SBCONFIG_PORT or SBCONFIG_HOSTNAME environment variable replaces the port or host option. Without them, the builder’s defaults apply: port 9009 on localhost.

This migration updates every @storybook/angular:start-storybook target in your projects. A target without its own executor is updated too when a targetDefaults entry in nx.json gives it @storybook/angular:start-storybook.

The migration leaves the readyWhen of a target unchanged in these cases:

• The target already sets readyWhen, including null.
• The target sets continuous: false, or sets no continuous and the targetDefaults entry that applies to it sets continuous: false.
• The targetDefaults entry that applies to the target sets readyWhen.

Nx checks readiness only for continuous targets. So the migration also sets continuous: true on the targets with their own @storybook/angular:start-storybook executor, unless the target or the targetDefaults entry that applies to it sets continuous. It skips a target whose options, or any of whose configurations, set smokeTest: true. Storybook exits once it starts in that mode, so the target doesn’t run a server. The setting can come from the target or from the targetDefaults entry that applies to it, and the target’s own value wins.

Sample code changes

Before

libs/ui/project.json

{
  // ...
  "targets": {
    "storybook": {
      "executor": "@storybook/angular:start-storybook",
      "continuous": true,
      "options": {
        "port": 4400,
        "configDir": "libs/ui/.storybook",
        "browserTarget": "ui:build-storybook"
      }
    }
  }
}

After

libs/ui/project.json

{
  // ...
  "targets": {
    "storybook": {
      "executor": "@storybook/angular:start-storybook",
      "continuous": true,
      "options": {
        "port": 4400,
        "configDir": "libs/ui/.storybook",
        "browserTarget": "ui:build-storybook"
      },
      "readyWhen": {
        "port": "{env.SBCONFIG_PORT ?? options.port ?? 9009}",
        "host": "{env.SBCONFIG_HOSTNAME ?? options.host ?? localhost}"
      }
    }
  }
}

update-24-0-1-add-highlight-ids

Version: 24.0.1-beta.0

Adds an id to Storybook HIGHLIGHT payloads emitted through useChannel, which Storybook 9.1.21 and 10.6.2 ignore without one. An AI prompt then finishes the Highlight changes in every file that uses storybook/highlight or clickEvent, including menu items that must replace clickEvent with clickable and a HIGHLIGHT_MENU_CLICK listener.

Requires

Name	Version
storybook	`>=9.1.21 <10.0.0

Add ids to Storybook Highlight payloads

Storybook 9.1.21 and 10.6.2 ignore a HIGHLIGHT payload that uses selectors without a string id. Storybook logs a warning in the browser console and draws nothing. Earlier versions drew the highlight and added a new one for every emit.

This migration adds an id to the payloads it can change without breaking a type check. These are object literals without an id, emitted through an emitter returned by useChannel from storybook/preview-api, as in the Storybook docs. Storybook types that emitter’s payload as any. The event can be HIGHLIGHT imported from storybook/highlight under any name, or its string value storybook/highlight/add.

The id is the file path followed by a random suffix, such as `apps/app/.storybook/preview.ts-${Math.random().toString(36).slice(2)}`. Every emit gets a new id, so each one adds its own highlight, as in earlier versions. Storybook builds the ids of legacy elements payloads the same way. To make a later emit replace the earlier highlight, change the id to a fixed string.

The migration then lists every file that uses storybook/highlight or clickEvent, including the files it changed. In agentic runs, an AI agent finishes the Highlight changes in those files:

• It gives an id to the other payloads, such as payloads emitted through addons.getChannel(), through a typed emitter or from a variable.
• It replaces clickEvent in menu items with clickable: true. A click now emits HIGHLIGHT_MENU_CLICK with the highlight id, the menu item id and the click details, so the agent moves the clickEvent listener to that event.
• It replaces reads of outerHTML and attributes on the element of the click details, which no longer has them.
• It adds an id to objects typed HighlightOptions, which now requires one.

Sample code changes

Before

apps/app/.storybook/preview.ts

import { useChannel } from 'storybook/preview-api';
import { HIGHLIGHT } from 'storybook/highlight';

export const decorators = [
  (storyFn) => {
    const emit = useChannel({});
    emit(HIGHLIGHT, { selectors: ['h2'] });
    return storyFn();
  },
];

After

apps/app/.storybook/preview.ts

import { useChannel } from 'storybook/preview-api';
import { HIGHLIGHT } from 'storybook/highlight';

export const decorators = [
  (storyFn) => {
    const emit = useChannel({});
    emit(HIGHLIGHT, {
      id: `apps/app/.storybook/preview.ts-${Math.random().toString(36).slice(2)}`,
      selectors: ['h2'],
    });
    return storyFn();
  },
];

Reference

• Storybook migration guide for Highlight menu items and ids

24.0.1-storybook-8-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/angular	^8.6.19	Updated only
@storybook/react	^8.6.19	Updated only
storybook	^8.6.19	Added if not installed
@storybook/addon-onboarding	^8.6.19	Updated only
@storybook/addon-themes	^8.6.19	Updated only
@storybook/builder-webpack5	^8.6.19	Updated only
@storybook/core-webpack	^8.6.19	Updated only
@storybook/html	^8.6.19	Updated only
@storybook/html-vite	^8.6.19	Updated only
@storybook/nextjs	^8.6.19	Updated only
@storybook/preact	^8.6.19	Updated only
@storybook/preact-vite	^8.6.19	Updated only
@storybook/react-vite	^8.6.19	Updated only
@storybook/react-webpack5	^8.6.19	Updated only
@storybook/server	^8.6.19	Updated only
@storybook/server-webpack5	^8.6.19	Updated only
@storybook/svelte	^8.6.19	Updated only
@storybook/svelte-vite	^8.6.19	Updated only
@storybook/sveltekit	^8.6.19	Updated only
@storybook/vue3	^8.6.19	Updated only
@storybook/vue3-vite	^8.6.19	Updated only
@storybook/web-components	^8.6.19	Updated only
@storybook/web-components-vite	^8.6.19	Updated only
@storybook/addon-essentials	^8.6.19	Updated only

24.0.1-storybook-9-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/angular	^9.1.21	Updated only
@storybook/react	^9.1.21	Updated only
storybook	^9.1.21	Added if not installed
@storybook/addon-onboarding	^9.1.21	Updated only
@storybook/addon-themes	^9.1.21	Updated only
@storybook/builder-webpack5	^9.1.21	Updated only
@storybook/core-webpack	^9.1.21	Updated only
@storybook/html	^9.1.21	Updated only
@storybook/html-vite	^9.1.21	Updated only
@storybook/nextjs	^9.1.21	Updated only
@storybook/preact	^9.1.21	Updated only
@storybook/preact-vite	^9.1.21	Updated only
@storybook/react-vite	^9.1.21	Updated only
@storybook/react-webpack5	^9.1.21	Updated only
@storybook/server	^9.1.21	Updated only
@storybook/server-webpack5	^9.1.21	Updated only
@storybook/svelte	^9.1.21	Updated only
@storybook/svelte-vite	^9.1.21	Updated only
@storybook/sveltekit	^9.1.21	Updated only
@storybook/vue3	^9.1.21	Updated only
@storybook/vue3-vite	^9.1.21	Updated only
@storybook/web-components	^9.1.21	Updated only
@storybook/web-components-vite	^9.1.21	Updated only
@storybook/addon-a11y	^9.1.21	Updated only
@storybook/addon-vitest	^9.1.21	Updated only

24.0.1-storybook-10-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/angular	^10.6.2	Updated only
@storybook/react	^10.6.2	Updated only
storybook	^10.6.2	Added if not installed
@storybook/addon-onboarding	^10.6.2	Updated only
@storybook/addon-themes	^10.6.2	Updated only
@storybook/builder-webpack5	^10.6.2	Updated only
@storybook/core-webpack	^10.6.2	Updated only
@storybook/html	^10.6.2	Updated only
@storybook/html-vite	^10.6.2	Updated only
@storybook/nextjs	^10.6.2	Updated only
@storybook/preact	^10.6.2	Updated only
@storybook/preact-vite	^10.6.2	Updated only
@storybook/react-vite	^10.6.2	Updated only
@storybook/react-webpack5	^10.6.2	Updated only
@storybook/server	^10.6.2	Updated only
@storybook/server-webpack5	^10.6.2	Updated only
@storybook/svelte	^10.6.2	Updated only
@storybook/svelte-vite	^10.6.2	Updated only
@storybook/sveltekit	^10.6.2	Updated only
@storybook/vue3	^10.6.2	Updated only
@storybook/vue3-vite	^10.6.2	Updated only
@storybook/web-components	^10.6.2	Updated only
@storybook/web-components-vite	^10.6.2	Updated only
@storybook/addon-a11y	^10.6.2	Updated only
@storybook/addon-vitest	^10.6.2	Updated only

24.0.1-storybook-core-8-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/core	^8.6.19	Updated only

24.0.1-storybook-core-server-8-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/core-server	^8.6.19	Updated only

24.0.1-storybook-experimental-addon-test-8-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/experimental-addon-test	^8.6.19	Updated only

24.0.1-storybook-addon-mcp-10-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/addon-mcp	^10.6.2	Updated only

24.0.1-chromatic-storybook-3-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@chromatic-com/storybook	^3.2.8	Updated only

24.0.1-chromatic-storybook-4-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@chromatic-com/storybook	^4.1.4	Updated only

24.0.1-chromatic-storybook-5-package-updates

Version: 24.0.1-beta.0

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@chromatic-com/storybook	^5.5.1	Updated only

23.2.x

23.2.0-test-runner-package-updates

Version: 23.2.0-beta.8

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/test-runner	^0.24.0	Updated only

23.1.x

23.1.0-package-updates

Version: 23.1.0-rc.3

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/angular	^10.5.0	Updated only
@storybook/react	^10.5.0	Updated only
storybook	^10.5.0	Added if not installed
@storybook/addon-onboarding	^10.5.0	Updated only
@storybook/addon-themes	^10.5.0	Updated only
@storybook/builder-webpack5	^10.5.0	Updated only
@storybook/core-webpack	^10.5.0	Updated only
@storybook/html	^10.5.0	Updated only
@storybook/html-vite	^10.5.0	Updated only
@storybook/nextjs	^10.5.0	Updated only
@storybook/preact	^10.5.0	Updated only
@storybook/preact-vite	^10.5.0	Updated only
@storybook/react-vite	^10.5.0	Updated only
@storybook/react-webpack5	^10.5.0	Updated only
@storybook/server	^10.5.0	Updated only
@storybook/server-webpack5	^10.5.0	Updated only
@storybook/svelte	^10.5.0	Updated only
@storybook/svelte-vite	^10.5.0	Updated only
@storybook/sveltekit	^10.5.0	Updated only
@storybook/vue3	^10.5.0	Updated only
@storybook/vue3-vite	^10.5.0	Updated only
@storybook/web-components	^10.5.0	Updated only
@storybook/web-components-vite	^10.5.0	Updated only

23.0.x

update-23-0-0-migrate-create-nodes-v2-import

Version: 23.0.0-beta.24

Rename imports of createNodesV2 from @nx/storybook/plugin to the canonical createNodes export.

Rename createNodesV2 imports to createNodes

@nx/storybook renamed its primary inferred-plugin export from createNodesV2 to createNodes. The createNodesV2 name is preserved as a deprecated alias for now, but new code should use createNodes.

This migration scans every .ts, .tsx, .cts, and .mts file in your workspace and rewrites named imports and re-exports of createNodesV2 from @nx/storybook/plugin to createNodes.

Sample Code Changes

Before

import { createNodesV2 } from '@nx/storybook/plugin';

After

import { createNodes } from '@nx/storybook/plugin';

Aliases are preserved (createNodesV2 as cn becomes createNodes as cn), and if a file already imports both names ({ createNodes, createNodesV2 }) the redundant binding is dropped.

What is not rewritten

Only static import/export named bindings from @nx/storybook/plugin are rewritten. Namespace imports, dynamic import(...), require(...) destructuring, and property access such as plugin.createNodesV2 are left untouched — they keep working through the createNodesV2 runtime alias. Update those by hand if you want to drop the deprecated name everywhere.

22.2.x

22.2.0-package-updates

Version: 22.2.0-beta.1

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/angular	^10.1.0	Updated only
@storybook/react	^10.1.0	Updated only
storybook	^10.1.0	Added if not installed
@storybook/addon-onboarding	^10.1.0	Updated only
@storybook/addon-themes	^10.1.0	Updated only
@storybook/builder-webpack5	^10.1.0	Updated only
@storybook/core-webpack	^10.1.0	Updated only
@storybook/html	^10.1.0	Updated only
@storybook/html-vite	^10.1.0	Updated only
@storybook/nextjs	^10.1.0	Updated only
@storybook/preact	^10.1.0	Updated only
@storybook/preact-vite	^10.1.0	Updated only
@storybook/react-vite	^10.1.0	Updated only
@storybook/react-webpack5	^10.1.0	Updated only
@storybook/server	^10.1.0	Updated only
@storybook/server-webpack5	^10.1.0	Updated only
@storybook/svelte	^10.1.0	Updated only
@storybook/svelte-vite	^10.1.0	Updated only
@storybook/sveltekit	^10.1.0	Updated only
@storybook/vue3	^10.1.0	Updated only
@storybook/vue3-vite	^10.1.0	Updated only
@storybook/web-components	^10.1.0	Updated only
@storybook/web-components-vite	^10.1.0	Updated only

22.1.x

update-22-1-0-migrate-storybook-v10

Version: 22.1.0-beta.8

Update workspace to use Storybook v10

Requires

Name	Version
storybook	>=10.0.0

21.1.0-package-updates

Version: 22.1.0-beta.3

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/angular	^9.0.5	Updated only
@storybook/react	^9.0.5	Updated only
storybook	^9.0.5	Added if not installed
@storybook/addon-onboarding	^9.0.5	Updated only
@storybook/addon-themes	^9.0.5	Updated only
@storybook/builder-webpack5	^9.0.5	Updated only
@storybook/core-webpack	^9.0.5	Updated only
@storybook/html	^9.0.5	Updated only
@storybook/html-vite	^9.0.5	Updated only
@storybook/nextjs	^9.0.5	Updated only
@storybook/preact	^9.0.5	Updated only
@storybook/preact-vite	^9.0.5	Updated only
@storybook/react-vite	^9.0.5	Updated only
@storybook/react-webpack5	^9.0.5	Updated only
@storybook/server	^9.0.5	Updated only
@storybook/server-webpack5	^9.0.5	Updated only
@storybook/svelte	^9.0.5	Updated only
@storybook/svelte-vite	^9.0.5	Updated only
@storybook/sveltekit	^9.0.5	Updated only
@storybook/vue3	^9.0.5	Updated only
@storybook/vue3-vite	^9.0.5	Updated only
@storybook/web-components	^9.0.5	Updated only
@storybook/web-components-vite	^9.0.5	Updated only

22.1.0-package-updates

Version: 22.1.0-beta.8

Packages

The following packages will be updated:

Name	Version	Always add to package.json
@storybook/angular	^10.0.0	Updated only
@storybook/react	^10.0.0	Updated only
storybook	^10.0.0	Added if not installed
@storybook/addon-onboarding	^10.0.0	Updated only
@storybook/addon-themes	^10.0.0	Updated only
@storybook/builder-webpack5	^10.0.0	Updated only
@storybook/core-webpack	^10.0.0	Updated only
@storybook/html	^10.0.0	Updated only
@storybook/html-vite	^10.0.0	Updated only
@storybook/nextjs	^10.0.0	Updated only
@storybook/preact	^10.0.0	Updated only
@storybook/preact-vite	^10.0.0	Updated only
@storybook/react-vite	^10.0.0	Updated only
@storybook/react-webpack5	^10.0.0	Updated only
@storybook/server	^10.0.0	Updated only
@storybook/server-webpack5	^10.0.0	Updated only
@storybook/svelte	^10.0.0	Updated only
@storybook/svelte-vite	^10.0.0	Updated only
@storybook/sveltekit	^10.0.0	Updated only
@storybook/vue3	^10.0.0	Updated only
@storybook/vue3-vite	^10.0.0	Updated only
@storybook/web-components	^10.0.0	Updated only
@storybook/web-components-vite	^10.0.0	Updated only

21.2.x

update-21-2-0-migrate-storybook-v9

Version: 21.2.0-beta.3

Update workspace to use Storybook v9

Requires

Name	Version
storybook	>=9.0.0 <10.0.0

update-21-2-0-remove-addon-dependencies

Version: 21.2.0-beta.3

Remove deprecated Storybook addon dependencies

Requires

Name	Version
storybook	>=9.0.0 <10.0.0