CLI: Improve support for upgrading Storybook in monorepos #31557

yannbf · 2025-05-23T13:21:28Z

What I did

This PR completely revamps our upgrade process to introduce better mono repository and introduces a visually improved CLI experience for the upgrade.

Improved upgrade experience for mono-repositories

Storybook's upgrade CLI (npx storybook@<next|latest> upgrade) should now always be executed in your project root. The CLI automatically detects all of your Storybook projects. If the Storybook projects are truly encapsulated, you can choose to upgrade one by one. Otherwise, we will upgrade all of your Storybooks at once.

Upgrade: Slimed down messaging and collecting results

The previous upgrade experience was packed with a lot of messages and links. Also, the upgrade CLI was shining in a variety of colors. We have reduced messaging to a minimum and outsourced debugging messages, warnings and errors to a debug log.

Additionally: We have also introduced new flags to introduce different log levels and to write all upgrade logs to a log file:

--write-logs: Write all debug logs to a file at the end of the run
--loglevel: <trace | debug | info | warn | error | silent> Define log level (default: "info")

Improved the `doctor` integration inside of upgrade

The doctor command was fine-tuned to collect results from multiple projects simultaneously. A user upgrading multiple Storybooks at once will get exact information of what kind of conflicts they have for a particular Storybook.

Introducing the technical foundation to adjust other parts of our CLI

We have revived the @storybook/node-logger package to encapsulate tooling for logging. Via a simple mechanism, we can switch the internal implementation of our loggers and prompt functions from the prompt and boxen library to the new modern package clack.

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 section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

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-31557-sha-a944b962. Try it out in a new sandbox by running npx [email protected] sandbox or in an existing project with npx [email protected] upgrade.

More information


Published version	`0.0.0-pr-31557-sha-a944b962`
Triggered by	@yannbf
Repository	storybookjs/storybook
Branch	`valentin/monorepo-enhancements`
Commit	`a944b962`
Datetime	Tue Jun 10 14:52:13 UTC 2025 (`1749567133`)
Workflow run	15562859477

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 canary-release-pr.yml --field pr=31557

Greptile Summary

Comprehensive overhaul of Storybook's upgrade process to improve monorepo support and CLI experience, focusing on centralized logging and user interaction improvements.

Revamped upgrade CLI to detect and manage multiple Storybook instances in monorepos through a new @storybook/node-logger package
Streamlined CLI messaging with configurable log levels (trace/debug/info/warn/error/silent) and optional log file output via --write-logs flag
Enhanced doctor command to collect and display diagnostics from multiple projects simultaneously
Introduced new Clack-based prompts system with improved visual feedback and error handling
Added monorepo-aware package management with intelligent project root detection and dependency resolution

CLI: Add prompts abstraction

…he project root

greptile-apps

_{192 files reviewed, 33 comments}
_{Edit PR Review Bot Settings | Greptile}

greptile-apps · 2025-06-10T13:55:10Z

code/lib/cli-storybook/test/helpers.cjs

+const cleanLog = (str) => {
+  const pattern = [
+    '[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)',
+    '(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))',
+  ].join('|');
+
+  return str.replace(new RegExp(pattern, 'g'), '');
+};


style: Consider making the regex pattern a constant to avoid recompiling it on every function call. This would improve performance when cleanLog is called frequently.

Suggested change

const cleanLog = (str) => {

const pattern = [

'[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)',

'(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))',

].join('|');

return str.replace(new RegExp(pattern, 'g'), '');

};

const ANSI_PATTERN = new RegExp([

'[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]+)*|[a-zA-Z\\d]+(?:;[-a-zA-Z\\d\\/#&.:=?%@~_]*)*)?\\u0007)',

'(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-ntqry=><~]))',

].join('|'), 'g');

const cleanLog = (str) => {

return str.replace(ANSI_PATTERN, '');

};

greptile-apps · 2025-06-10T13:55:11Z

code/core/src/core-server/utils/warnOnIncompatibleAddons.ts

 import {
  getIncompatiblePackagesSummary,
  getIncompatibleStorybookPackages,
 } from '../../../../lib/cli-storybook/src/doctor/getIncompatibleStorybookPackages';


style: Consider using direct imports instead of importing through 4 directory levels with '../../../../'

greptile-apps · 2025-06-10T13:55:12Z

code/core/src/core-server/utils/get-new-story-file.ts

  const storyFilePath =
-    doesStoryFileExist(join(cwd, dir), storyFileName) && componentExportCount > 1
-      ? join(cwd, dir, alternativeStoryFileNameWithExtension)
-      : join(cwd, dir, storyFileNameWithExtension);
+    doesStoryFileExist(join(getProjectRoot(), dir), storyFileName) && componentExportCount > 1
+      ? join(getProjectRoot(), dir, alternativeStoryFileNameWithExtension)
+      : join(getProjectRoot(), dir, storyFileNameWithExtension);



style: Repetitive getProjectRoot() calls could be optimized by storing result in a variable

Suggested change

const storyFilePath =

doesStoryFileExist(join(cwd, dir), storyFileName) && componentExportCount > 1

? join(cwd, dir, alternativeStoryFileNameWithExtension)

: join(cwd, dir, storyFileNameWithExtension);

doesStoryFileExist(join(getProjectRoot(), dir), storyFileName) && componentExportCount > 1

? join(getProjectRoot(), dir, alternativeStoryFileNameWithExtension)

: join(getProjectRoot(), dir, storyFileNameWithExtension);

const projectRoot = getProjectRoot();

const storyFilePath =

doesStoryFileExist(join(projectRoot, dir), storyFileName) && componentExportCount > 1

? join(projectRoot, dir, alternativeStoryFileNameWithExtension)

: join(projectRoot, dir, storyFileNameWithExtension);

greptile-apps · 2025-06-10T13:55:12Z

code/core/src/node-logger/prompts/prompt-functions.ts

+  TaskLogOptions,
+  TextPromptOptions,
+} from './prompt-provider-base';
+import { asyncLocalStorage } from './storage';


style: asyncLocalStorage is imported but never used

greptile-apps · 2025-06-10T13:55:15Z

code/core/src/cli/eslintPlugin.ts

+  const allDependencies = packageManager.getAllDependencies();
+  const { packageJson } = packageManager.primaryPackageJson;


logic: getAllDependencies() called without await but appears to be synchronous now - verify this change is intentional

greptile-apps · 2025-06-10T14:00:03Z

code/core/src/telemetry/get-monorepo-type.ts

+    const configFile = join(getProjectRoot(), monorepoConfigs[monorepo]);
    return existsSync(configFile);


style: getProjectRoot() called multiple times may introduce overhead if expensive. Consider storing result in a variable.

greptile-apps · 2025-06-10T14:00:03Z

code/core/src/node-logger/wrap-utils.ts

+function getEnvFromTerminal(key: string): string {
+  return execaSync('echo', [`$${key}`], { shell: true }).stdout.trim();
+}


logic: Shell command execution can fail in restricted environments. Consider using process.env directly as a safer fallback.

greptile-apps · 2025-06-10T14:00:07Z

code/core/src/common/js-package-manager/Yarn1Proxy.test.ts

    it('throws an error if command output is not a valid JSON', async () => {
-      vi.spyOn(yarn1Proxy, 'executeCommand').mockResolvedValueOnce('NOT A JSON');
+      vi.spyOn(yarn1Proxy, 'executeCommand').mockReturnValue(
+        Promise.resolve({ stdout: 'NOT A JSON' }) as any
+      );

-      await expect(yarn1Proxy.latestVersion('storybook')).rejects.toThrow();
+      await expect(yarn1Proxy.latestVersion('storybook')).resolves.toBe(null);
    });


logic: Error handling behavior changed from throwing to returning null. Ensure this change was intentional and documented, as it affects error handling in dependent code

Suggested change

it('throws an error if command output is not a valid JSON', async () => {

vi.spyOn(yarn1Proxy, 'executeCommand').mockResolvedValueOnce('NOT A JSON');

vi.spyOn(yarn1Proxy, 'executeCommand').mockReturnValue(

Promise.resolve({ stdout: 'NOT A JSON' }) as any

);

await expect(yarn1Proxy.latestVersion('storybook')).rejects.toThrow();

await expect(yarn1Proxy.latestVersion('storybook')).resolves.toBe(null);

});

it('returns null if command output is not a valid JSON', async () => {

vi.spyOn(yarn1Proxy, 'executeCommand').mockReturnValue(

Promise.resolve({ stdout: 'NOT A JSON' }) as any

);

await expect(yarn1Proxy.latestVersion('storybook')).resolves.toBe(null);

});

greptile-apps · 2025-06-10T14:04:50Z

code/lib/cli-storybook/src/migrate.ts

-  migration: any,
-  { glob, dryRun, list, rename, parser, configDir: userSpecifiedConfigDir }: CLIOptions
-) {
+export async function migrate(migration: any, { glob, dryRun, list, rename, parser }: CLIOptions) {


logic: The configDir option is defined in CLIOptions but not destructured in the function parameters

greptile-apps · 2025-06-10T14:04:56Z

code/core/src/node-logger/logger/logger.ts

+    if (level === 'prompt') {
+      level = 'info';
+    }


logic: Mutating level parameter can cause unexpected behavior. Consider using a new variable

…ents CLI: Improve support for upgrading Storybook in monorepos (cherry picked from commit 9c2f2fd)

ndelangen · 2025-10-01T09:46:49Z

@valentinpalkovic can you please add a manual testing section, so we can do QA?

valentinpalkovic · 2025-10-01T10:05:18Z

This feature was already properly QAed for 9.1. It was missed to remove the needs QA after the release.

yannbf and others added 30 commits May 22, 2025 11:40

add prompts abstraction

8536401

experiment with clack

ad924e8

Encapsulate boxen usage in cli-storybook

a718ece

cleanup

745682d

cleanup

16531c5

fix types

b7df284

use onCancel as a base option

7991203

fix tests

50e1bd2

try to fix test on windows

6cee77a

fix

3a55010

Merge pull request #31521 from storybookjs/yann/prompts-abstraction

721aba0

CLI: Add prompts abstraction

detect multiple config dirs for the upgrade command

bd45265

updates

336c11f

fix types

b9fe8b5

remove unused code

01c350d

further updates

6356cf3

Core: Improve mono repo handling for JsPackageManager class and helpers

c13b712

Fix Angular sandbox

566b526

Remove unused import

4737b92

Fix types

6436065

Smaller fixes

5595040

Install at the end of automigrations

eac2647

Fix tests

69b3764

Core: Use projectRoot consequently and limit find-up actions to t…

ef8f4f2

…he project root

fix tests

b3e5ca2

Revert projectRoot usage to getProjectRoot

852679e

Fix initialization in empty directory + improvements in init

7edd821

Fix import and reference issues

034dbf6

Fix tests

4092bac

fix tests

480594b

yannbf added 5 commits June 10, 2025 15:31

skip more tests

d6f8b09

remove obsolete snapshots

df702a3

skip other tests

8ec5f60

allow varags in logger functions

dbd6a74

Merge branch 'next' into valentin/monorepo-enhancements

a944b96

yannbf marked this pull request as ready for review June 10, 2025 13:54

valentinpalkovic approved these changes Jun 10, 2025

View reviewed changes

greptile-apps bot reviewed Jun 10, 2025

View reviewed changes

yannbf merged commit 9c2f2fd into next Jun 10, 2025
63 checks passed

yannbf deleted the valentin/monorepo-enhancements branch June 10, 2025 14:55

github-actions bot mentioned this pull request Jun 10, 2025

Release: Prerelease 9.1.0-alpha.6 #31737

Merged

7 tasks

valentinpalkovic added the patch:yes Bugfix & documentation PR that need to be picked to main branch label Jun 17, 2025

github-actions bot mentioned this pull request Jun 17, 2025

Release: Patch 9.0.12 #31801

Merged

15 tasks

valentinpalkovic pushed a commit that referenced this pull request Jun 17, 2025

Merge pull request #31557 from storybookjs/valentin/monorepo-enhancem…

fd74caa

…ents CLI: Improve support for upgrading Storybook in monorepos (cherry picked from commit 9c2f2fd)

github-actions bot mentioned this pull request Jun 18, 2025

Release: Patch 9.0.12 #31810

Closed

15 tasks

github-actions bot added the patch:done Patch/release PRs already cherry-picked to main/release branch label Jun 18, 2025

DavideMininni-Fincons mentioned this pull request Jun 26, 2025

[Bug]: compodoc command broken migrating from 9.0.11 to 9.0.12 #31880

Closed

yannbf added the needs qa Indicates that this needs manual QA during the upcoming minor/major release label Jul 25, 2025

github-actions bot mentioned this pull request Aug 13, 2025

[master] Michijs Dependabot changes michijs/michijs-storybook-template#68

Closed

ndelangen unassigned yannbf Oct 1, 2025

valentinpalkovic removed the needs qa Indicates that this needs manual QA during the upcoming minor/major release label Oct 1, 2025

penicillin0 mentioned this pull request Oct 8, 2025

Makes it available even in versions below 9.12.0 storybookjs/mcp#19

Closed

ndelangen removed the patch:yes Bugfix & documentation PR that need to be picked to main branch label Oct 28, 2025

		const allDependencies = packageManager.getAllDependencies();
		const { packageJson } = packageManager.primaryPackageJson;

		const configFile = join(getProjectRoot(), monorepoConfigs[monorepo]);
		return existsSync(configFile);

Uh oh!

CLI: Improve support for upgrading Storybook in monorepos #31557

CLI: Improve support for upgrading Storybook in monorepos #31557

Uh oh!

Conversation

yannbf commented May 23, 2025 • edited by storybook-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I did

Improved upgrade experience for mono-repositories

Upgrade: Slimed down messaging and collecting results

Improved the doctor integration inside of upgrade

Introducing the technical foundation to adjust other parts of our CLI

Checklist for Contributors

Testing

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

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

Greptile Summary

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot Jun 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ndelangen commented Oct 1, 2025

Uh oh!

valentinpalkovic commented Oct 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yannbf commented May 23, 2025 •

edited by storybook-bot

Loading

Improved the `doctor` integration inside of upgrade