CLI: Modernize Storybook CLI with new init workflow, Clack UI, and Generator System

[valentinpalkovic]

Closes #25389
Closes #32043
Closes #32778
Closes #31880
Closes #31914

What I did

This PR represents a massive refactor and modernization of the Storybook CLI, primarily focused on the init command. The original initiate.ts file, a monolithic, 900+ line behemoth, was brittle, hard to maintain, and difficult to test.

This new architecture replaces it with a clean, command-based pipeline that is modular, testable, and far more extensible. We've also swapped our CLI's user interface from prompts to @clack/prompts, providing a significantly improved, modern, and interactive experience for users.

Highlights of the Change

Command-Based init Workflow: The entire init process is now orchestrated as a series of discrete, testable commands:

• PreflightCheckCommand: Handles empty directory scaffolding and package manager setup.
• ProjectDetectionCommand: Detects the project type (e.g., React, Angular).
• FrameworkDetectionCommand: Determines the correct Storybook framework, builder, and renderer.
• UserPreferencesCommand: Handles all user interaction (New user? Install type?).
• GeneratorExecutionCommand: Runs the appropriate framework-specific generator.
• DependencyInstallationCommand: Collects all dependencies and installs them in a single step.
• AddonConfigurationCommand: Runs post-install configuration for addons like a11y and vitest.
• FinalizationCommand: Updates .gitignore and prints success messages.

New Generator System:
Introduced a generatorRegistry and a new GeneratorModule interface.

All framework generators (React, Angular, Next.js, Nuxt, etc.) have been refactored to this new, modular standard, separating metadata and configuration logic .

Modern Clack UI:

• Replaced prompts, ora, and boxen with @clack/prompts across the entire CLI (init, add, upgrade, automigrate) for a unified, beautiful, and interactive experience.

Centralized Addon & Feature Logic:

• AddonVitestService: A new, centralized service that manages all logic for the test feature. It handles compatibility validation, dependency collection, and configuration, ensuring logic is no longer duplicated between init and add .
• DependencyCollector: A new class that gathers all required dependencies before installation, allowing us to run a single npm install/yarn add at the end of the init process .

a11y in recommended:
The test feature now also includes @storybook/addon-a11y by default, as it's a prerequisite for accessibility testing.

New Next.js-Vite Support:

• The Next.js generator now defaults to @storybook/nextjs-vite (Vite builder) for new projects. It intelligently detects custom webpack.config.js or .babelrc files and prompts the user to fall back to @storybook/nextjs (Webpack 5) if needed.

• Added a new nextjs-to-nextjs-vite automigration to help users move from the old Webpack-based setup .

Rsbuild Support during initialization:

• When initializing Storybook in an rsbuild-based project, we will set up your project properly if rsbuild is used with one of the supported renderers: lit, react, vue, vanilla js.

Enhanced Logging & Error Handling:

• All CLI commands now use the standardized logger and prompt from node-logger.
• Builder output (Vite) is now prefixed for clarity (e.g., [Vite] ...). Webpack was not adjusted yet due to its complex nature of logging items (status)
• All CLI commands (init, add, automigrate) will now reliably generate a debug-storybook.log file on failure, making debugging much easier.

Introduced new StorybookError subclasses for CLI failures (e.g., AddonVitestPostinstallError)

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

This is a massive change. Please test the init and add commands thoroughly.

storybook init

1. The "Golden Path":

• cd into a new React + Vite project.
• Run npx storybook@<canary> init.
• ✅ Assert: You see the new Clack UI.
• ✅ Assert: You are prompted "New to Storybook?" > "What configuration?". Select "Recommended".
• ✅ Assert: It installs all recommended dependencies, including test (@storybook/addon-vitest, vitest, etc.) and a11y (@storybook/addon-a11y).
• ✅ Assert: It prompts you to install Playwright binaries.
• ✅ Assert: The final success message lists docs, test, a11y, onboarding.

2. Non-Interactive (--yes):

• cd into a new React + Vite project.
• Run npx storybook@<canary> init --yes.
• ✅ Assert: No prompts appear.
• ✅ Assert: The result is identical to the "Recommended" install (all features included).

3. Feature Selection:

• cd into a new React + Vite project.
• Run npx storybook@latest init --features docs a11y.
• ✅ Assert: No prompts for "New User" or "Install Type" appear.
• ✅ Assert: Only @storybook/addon-docs and @storybook/addon-a11y are installed. @storybook/addon-vitest and @storybook/addon-onboarding are not installed.

4. Next.js (Vite vs. Webpack):

• cd into a clean Next.js project. Run init --yes.
• ✅ Assert: It installs @storybook/nextjs-vite and vite.
• Now, rm -rf .storybook and add a webpack(config) { return config; } block to next.config.js.
• Run init interactively.
• ✅ Assert: It must prompt you to choose between @storybook/nextjs-vite (default) and @storybook/nextjs (Webpack).

storybook add

• cd into a project without the test feature (e.g., init --features docs).
• Run npx storybook@<canary> add @storybook/addon-vitest.
• ✅ Assert: The postinstall script runs.
• ✅ Assert: You see the Clack UI prompt to install Playwright.
• ✅ Assert: It creates vitest.config.ts.
• ✅ Assert: If you also have addon-a11y installed, it should run the a11y-addon-test automigration to configure it.

storybook automigrate

• cd into a project using the old @storybook/nextjs (Webpack).
• Run npx storybook@latest automigrate nextjs-to-nextjs-vite.
• ✅ Assert: package.json and main.ts are updated from @storybook/nextjs to @storybook/nextjs-vite.

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This pull request has been released as version 0.0.0-pr-32717-sha-7a16d827. Try it out in a new sandbox by running npx storybook@0.0.0-pr-32717-sha-7a16d827 sandbox or in an existing project with npx storybook@0.0.0-pr-32717-sha-7a16d827 upgrade.

More information

Published version	0.0.0-pr-32717-sha-7a16d827
Triggered by	@valentinpalkovic
Repository	storybookjs/storybook
Branch	valentin/cli-init-rework
Commit	7a16d827
Datetime	Wed Nov 19 10:25:34 UTC 2025 (1763547934)
Workflow run	19498001525

To request a new release of this pull request, mention the @storybookjs/core team.

core team members can create a new canary release here or locally with gh workflow run --repo storybookjs/storybook publish.yml --field pr=32717

Summary by CodeRabbit

• New Features

  • Modular init flow with pluggable generators and a dedicated addon-configuration command.

• Improvements

  • CLI: new --logfile and --loglevel options; "a11y" added to feature choices.
  • Smoother, more consistent logging and prompt UX across init, sandbox, and dev workflows.
  • Better automated handling for test integrations and dependency setup during initialization.

• Tests

  • Broader test coverage for init, generators, package managers, and migrations.

[coderabbitai]

📝 Walkthrough

Walkthrough

Modularized create/init flows, centralized command execution and logging/prompting, consolidated mocking utilities, introduced typed enums (frameworks, renderers, builders, features, languages, project types), reworked generator and command modules, refactored Vitest addon/postinstall and builder mocking integrations, and updated CI test-init features to include a11y.

Changes

Cohort / File(s)	Summary
CI config .circleci/config.yml, .circleci/src/jobs/test-init-features.yml	test-init-features changed Storybook init features to docs test a11y and sets --loglevel=debug.
Create-storybook & init orchestration code/lib/create-storybook/src/bin/run.ts, code/lib/create-storybook/src/initiate.ts, code/lib/create-storybook/src/commands/*, code/lib/create-storybook/src/commands/index.ts	Large refactor: split init into command modules (Preflight, ProjectDetection, FrameworkDetection, UserPreferences, GeneratorExecution, DependencyInstallation, AddonConfiguration, Finalization), telemetry wrappers, logfile/loglevel CLI options, many new command implementations and tests.
Generators & registry code/lib/create-storybook/src/generators/**, .../modules/GeneratorModule.ts, .../GeneratorRegistry.ts, .../registerGenerators.ts, .../types.ts	Convert generators to module form via defineGeneratorModule({ metadata, configure, postConfigure }); add GeneratorRegistry; change GeneratorOptions (features → Set, add DependencyCollector) and related public types.
Dependency collection & installation code/lib/create-storybook/src/dependency-collector.ts, .../DependencyInstallationCommand.ts, .../AddonConfigurationCommand.ts, .../FinalizationCommand.ts	Add DependencyCollector, dependency-install and addon-configuration commands, FinalizationCommand, ErrorCollector integration, and tests.
Node logger, prompts & tasks code/core/src/node-logger/**, code/core/src/core-server/*	Introduce ConsoleLogger/StyledConsoleLogger, refactor logTracker (writeToFile/shouldWriteLogsToFile), adopt clack-only prompt provider, add taskLog.group, BoxOptions/logBox, and switch many logs to logger.step/intro/outro.
Command execution util & package managers code/core/src/common/utils/command.ts, code/core/src/common/js-package-manager/*, *Proxy.ts	Add centralized execa-backed executeCommand/executeCommandSync/executeNodeCommand; change runPackageCommand to options-object { args, ... }; introduce PackageManagerName enum, package.json caching, update proxies/tests.
Mocking-utils consolidation code/core/src/mocking-utils/*, code/core/build-config.ts, builders' plugins/loaders	Consolidate automock/extract/resolve/esmWalker/runtime into internal/mocking-utils; add getMockerRuntime; change signatures (extractMockCalls, resolveMock) to accept findMockRedirect; update builders/loaders to import new APIs.
Builders — Vite code/builders/builder-vite/src/{logger,build,vite-server,preset,index}.ts, code/builders/builder-vite/package.json, code/builders/builder-vite/preset.js	Add createViteLogger and assign to Vite customLogger; add corePresets and preset to inject mock plugins; publish ./preset export and add @vitest/mocker dependency.
Builders — Webpack5 code/builders/builder-webpack5/src/presets/custom-webpack-preset.ts, .../loaders/*, .../plugins/*, package.json	Add webpackFinal to inject mock loaders/runtime, introduce loaders/plugins, switch imports to storybook/internal/mocking-utils, and export loaders in package.json with @vitest/mocker.
Addon Vitest & postinstall code/core/src/cli/AddonVitestService.ts, code/addons/vitest/src/*, code/core/src/server-errors.ts	Add AddonVitestService (collectDependencies, validateCompatibility, installPlaywright, validateConfigFiles), remove ad-hoc postinstall logger module, add StorybookError subclasses, and refactor postinstall flows to use the service; adjust many tests.
Addon registration & postinstall helper code/lib/cli-storybook/src/add.ts, code/lib/cli-storybook/src/postinstallAddon.ts, code/core/src/common/utils/setup-addon-in-config.ts	Delegate CSF addon registration to setupAddonInConfig; add postinstallAddon helper and getVersionSpecifier; extend PostinstallOptions with logger/prompt/skipDependencyManagement.
Core types & public API code/core/src/types/modules/*, code/core/src/cli/projectTypes.ts, code/core/package.json, code/core/src/common/index.ts, code/core/src/manager/globals/exports.ts	Replace many union types with enums: SupportedFramework, SupportedRenderer, SupportedBuilder, SupportedLanguage, Feature, ProjectType, CoreWebpackCompiler; add/adjust exports including internal/mocking-utils.
CLI detect & tests cleanup code/core/src/cli/detect.ts, code/core/src/cli/detect.test.ts	Remove legacy detection helpers and tests; simplify detect exports and reduce detection surface.
Logging & UX housekeeping multiple files across core, frameworks, lib, tests	Remove "=>" prefixes, migrate console/boxen/table into logger.logBox, standardize prompt usage to node-logger.prompt, replace many console/log calls with logger.step/intro/outro; update tests accordingly.
Misc — package.json & devDeps multiple package.json files	Remove unused devDeps (boxen, execa, prompts, ora, giget) across packages; adjust package exports and add @vitest/mocker to builders that need it.

Sequence Diagram(s)

%% Primary init/create-storybook flow (high level)
sequenceDiagram
  autonumber
  actor User
  participant CLI as "create-storybook CLI"
  participant Pre as "PreflightCheck"
  participant Detect as "ProjectDetection"
  participant Frm as "FrameworkDetection"
  participant Pref as "UserPreferences"
  participant Gen as "GeneratorExecution"
  participant Dep as "DependencyInstallation"
  participant Add as "AddonConfiguration"
  participant Fin as "Finalization"

  User->>CLI: initiate(options)
  CLI->>Pre: execute(options)
  Pre-->>CLI: { packageManager, isEmptyProject }
  CLI->>Detect: execute(...)
  Detect-->>CLI: { projectType, language }
  CLI->>Frm: execute(...)
  Frm-->>CLI: { renderer, builder, framework }
  CLI->>Pref: execute(...)
  Pref-->>CLI: { selectedFeatures }
  CLI->>Gen: execute(...)
  Gen-->>CLI: { configDir?, storybookCommand?, extraAddons }
  CLI->>Dep: execute(...)
  Dep-->>CLI: { status }
  CLI->>Add: execute(...)
  Add-->>CLI: { status }
  CLI->>Fin: execute(...)
  Fin-->>CLI: done

Loading

%% Addon Vitest interactions (high level)
sequenceDiagram
  autonumber
  participant Caller
  participant AddV as "AddonVitestService"
  participant PM as "JsPackageManager"

  Caller->>AddV: validateCompatibility(opts)
  AddV-->>Caller: { compatible, reasons? }
  Caller->>AddV: collectDependencies(PM)
  AddV-->>Caller: [packages]
  Caller->>AddV: validateConfigFiles(directory)
  AddV-->>Caller: { compatible, reasons? }
  Caller->>AddV: installPlaywright(PM, { yes? })
  AddV-->>Caller: errors[]

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~150 minutes

• Files/areas to focus review on:
  • mocking-utils consolidation and API changes: code/core/src/mocking-utils/* and builders/loaders now importing storybook/internal/mocking-utils.
  • JsPackageManager family and proxies: code/core/src/common/js-package-manager/* (new runPackageCommand shape, PackageManagerName enum, package.json caching, executeCommand integration).
  • create-storybook rearchitecture: code/lib/create-storybook/src/initiate.ts, the new commands/*, DependencyCollector, and generator conversions.
  • node-logger redesign: code/core/src/node-logger/* (logTracker.writeToFile behavior, prompt provider changes, BoxOptions/logBox, taskLog.group).
  • Addon Vitest service & postinstall flow: code/core/src/cli/AddonVitestService.ts, code/addons/vitest/src/*, and new StorybookError subclasses.
  • Builder integrations and preset/plugin injection: Vite/Webpack presets/plugins and code/core/src/core-server/load.ts wiring.

Possibly related issues

• [Tracking]: Modernize init flow #32643 — Modernize init flow: this PR implements the modular init/command architecture, generator-module API, and node-logger/prompt migration referenced by the issue.

Possibly related PRs

• CLI: Fix issue with running Storybook after being initialized #32929 — Refactors dev server spawn and introduces executeCommand/executeNodeCommand usage; strongly related to executeCommand/executeNodeCommand changes here.
• Core: Decouple Mocking Logic from Core into Builders #32921 — Mocking consolidation: overlaps moving mock helpers into a central mocking-utils surface and updating builders/loaders.
• Addon Vitest: Support modifying mergeConfig on addon setup #32753 — Vitest addon refactor: overlaps AddonVitestService, compatibility validation and Playwright install flows added in this PR.

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit b01def1

Command	Status	Duration	Result
nx run-many -t build --parallel=3	✅ Succeeded	45s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-11-19 12:57:28 UTC

[storybook-app-bot]

Package Benchmarks

^{Commit: b01def1, ran on 19 November 2025 at 12:48:58 UTC}

The following packages have significant changes to their size or dependencies:

@storybook/addon-a11y

	Before	After	Difference
Dependency count	2	2	0
Self size	414 KB	181 KB	🎉 -232 KB 🎉
Dependency size	2.97 MB	2.97 MB	0 B
Bundle Size Analyzer	Link	Link

@storybook/addon-vitest

	Before	After	Difference
Dependency count	6	2	🎉 -4 🎉
Self size	441 KB	375 KB	🎉 -66 KB 🎉
Dependency size	570 KB	338 KB	🎉 -232 KB 🎉
Bundle Size Analyzer	Link	Link

@storybook/builder-vite

	Before	After	Difference
Dependency count	11	17	🚨 +6 🚨
Self size	291 KB	304 KB	🚨 +13 KB 🚨
Dependency size	1.30 MB	2.00 MB	🚨 +701 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/builder-webpack5

	Before	After	Difference
Dependency count	187	191	🚨 +4 🚨
Self size	66 KB	75 KB	🚨 +9 KB 🚨
Dependency size	31.98 MB	32.19 MB	🚨 +215 KB 🚨
Bundle Size Analyzer	Link	Link

storybook

	Before	After	Difference
Dependency count	44	39	🎉 -5 🎉
Self size	21.70 MB	19.20 MB	🎉 -2.50 MB 🎉
Dependency size	17.16 MB	16.40 MB	🎉 -755 KB 🎉
Bundle Size Analyzer	Link	Link

@storybook/angular

	Before	After	Difference
Dependency count	187	191	🚨 +4 🚨
Self size	114 KB	118 KB	🚨 +3 KB 🚨
Dependency size	29.99 MB	30.22 MB	🚨 +224 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/ember

	Before	After	Difference
Dependency count	191	195	🚨 +4 🚨
Self size	15 KB	15 KB	0 B
Dependency size	28.69 MB	28.91 MB	🚨 +224 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/html-vite

	Before	After	Difference
Dependency count	14	20	🚨 +6 🚨
Self size	22 KB	22 KB	🚨 +12 B 🚨
Dependency size	1.63 MB	2.34 MB	🚨 +715 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/nextjs

	Before	After	Difference
Dependency count	533	537	🚨 +4 🚨
Self size	645 KB	645 KB	🎉 -5 B 🎉
Dependency size	58.91 MB	59.13 MB	🚨 +224 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/nextjs-vite

	Before	After	Difference
Dependency count	124	128	🚨 +4 🚨
Self size	1.12 MB	1.12 MB	🚨 +85 B 🚨
Dependency size	21.72 MB	21.95 MB	🚨 +229 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/preact-vite

	Before	After	Difference
Dependency count	14	20	🚨 +6 🚨
Self size	13 KB	13 KB	🚨 +12 B 🚨
Dependency size	1.61 MB	2.33 MB	🚨 +715 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/react-native-web-vite

	Before	After	Difference
Dependency count	156	160	🚨 +4 🚨
Self size	30 KB	30 KB	0 B
Dependency size	22.90 MB	23.13 MB	🚨 +229 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/react-vite

	Before	After	Difference
Dependency count	114	118	🚨 +4 🚨
Self size	35 KB	35 KB	🚨 +112 B 🚨
Dependency size	19.52 MB	19.75 MB	🚨 +229 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/react-webpack5

	Before	After	Difference
Dependency count	273	277	🚨 +4 🚨
Self size	24 KB	24 KB	🚨 +12 B 🚨
Dependency size	43.85 MB	44.08 MB	🚨 +224 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/server-webpack5

	Before	After	Difference
Dependency count	199	203	🚨 +4 🚨
Self size	16 KB	16 KB	0 B
Dependency size	33.23 MB	33.45 MB	🚨 +224 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/svelte-vite

	Before	After	Difference
Dependency count	19	24	🚨 +5 🚨
Self size	56 KB	56 KB	0 B
Dependency size	26.75 MB	27.00 MB	🚨 +255 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/sveltekit

	Before	After	Difference
Dependency count	20	25	🚨 +5 🚨
Self size	56 KB	56 KB	🎉 -24 B 🎉
Dependency size	26.80 MB	27.06 MB	🚨 +255 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/vue3-vite

	Before	After	Difference
Dependency count	109	114	🚨 +5 🚨
Self size	35 KB	35 KB	🎉 -24 B 🎉
Dependency size	43.90 MB	44.15 MB	🚨 +255 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/web-components-vite

	Before	After	Difference
Dependency count	15	21	🚨 +6 🚨
Self size	19 KB	19 KB	🎉 -12 B 🎉
Dependency size	1.65 MB	2.37 MB	🚨 +715 KB 🚨
Bundle Size Analyzer	Link	Link

@storybook/cli

	Before	After	Difference
Dependency count	188	173	🎉 -15 🎉
Self size	840 KB	770 KB	🎉 -70 KB 🎉
Dependency size	71.37 MB	66.17 MB	🎉 -5.21 MB 🎉
Bundle Size Analyzer	Link	Link

@storybook/codemod

	Before	After	Difference
Dependency count	170	166	🎉 -4 🎉
Self size	30 KB	30 KB	🎉 -25 B 🎉
Dependency size	67.91 MB	64.74 MB	🎉 -3.17 MB 🎉
Bundle Size Analyzer	Link	Link

create-storybook

	Before	After	Difference
Dependency count	45	40	🎉 -5 🎉
Self size	1.45 MB	998 KB	🎉 -454 KB 🎉
Dependency size	38.86 MB	35.60 MB	🎉 -3.25 MB 🎉
Bundle Size Analyzer	node	node