From 26a841f2854e20ca9d8a947e89c84f9ee06b12e3 Mon Sep 17 00:00:00 2001 From: Valentin Palkovic Date: Wed, 11 Jun 2025 11:04:01 +0200 Subject: [PATCH 01/10] Docs: Enhance upgrading guide with mono-repository support and automatic health check features --- docs/configure/upgrading.mdx | 81 ++++++++++++++++++++++++++++++++---- 1 file changed, 74 insertions(+), 7 deletions(-) diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index 30d7650569bb..afe4a4d5520d 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -11,7 +11,7 @@ The frontend ecosystem is a fast-moving place. Regular dependency upgrades are a The most common upgrade is Storybook itself. [Storybook releases](https://storybook.js.org/releases) follow [Semantic Versioning](https://semver.org/). We publish patch releases with bug fixes continuously, minor versions of Storybook with new features every few months, and major versions of Storybook with breaking changes roughly once per year. -To help ease the pain of keeping Storybook up-to-date, we provide a command-line script: +To help ease the pain of keeping Storybook up-to-date, we provide a command-line script that automatically detects all Storybook projects in your repository: {/* prettier-ignore-start */} @@ -19,6 +19,10 @@ To help ease the pain of keeping Storybook up-to-date, we provide a command-line {/* prettier-ignore-end */} + + **Important:** Always run the upgrade command from your repository root. The script will automatically detect all Storybook projects in your repository, including in mono-repository setups. + + The `upgrade` command will use whichever version you specify. For example: * `storybook@latest upgrade` will upgrade to the latest version @@ -36,24 +40,87 @@ The `upgrade` command will use whichever version you specify. For example: The only exception to this is when upgrading from 6 to 8, where you can run `storybook@8 upgrade` directly to upgrade from 6.x.x to 8.x.x. +### Mono-repository support + +The upgrade script now provides enhanced support for mono-repositories: + +- **Automatic detection**: The script automatically detects all Storybook projects in your repository +- **Selective upgrades**: If your Storybooks are truly encapsulated and don't share dependencies in shared `package.json` files, you can select which Storybook project to upgrade +- **Bulk upgrades**: If your Storybooks share dependencies, all detected projects will be upgraded together to ensure consistency + +### Limiting scope in large mono-repositories + +For large mono-repositories where you want to limit the upgrade to a specific directory, use the `STORYBOOK_PROJECT_ROOT` environment variable: + +```bash +STORYBOOK_PROJECT_ROOT=./packages/frontend storybook@latest upgrade +``` + +This is especially helpful in huge mono-repositories with semi-encapsulated Storybooks. + + +## Upgrade process + After running the command, the script will: -* Upgrade all Storybook packages in your project to the specified version +* Detect all Storybook projects in your repository +* Upgrade all Storybook packages to the specified version * Run the relevant [automigrations](../migration-guide/index.mdx#automatic-upgrade) factoring in the [breaking changes](../migration-guide/index.mdx#major-breaking-changes) between your current version and the specified version +* Automatically run the [doctor command](#automatic-health-check) to verify the upgrade In addition to running the command, we also recommend checking the [MIGRATION.md file](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md), for the detailed log of relevant changes and deprecations that might affect your upgrade. -### Verifying the upgrade +### Automatic health check -To help you verify that the upgrade was completed and that your project is still working as expected, the Storybook CLI provides the [`doctor`](../api/cli-options.mdx#doctor) command that allows you to do a health check on your project for common issues that might arise after an upgrade, such as duplicated dependencies, incompatible addons or mismatched versions. To perform the health check, run the following command with your package manager of choice: +The upgrade script now automatically runs a health check on all detected Storybook projects after the upgrade. This verifies that the upgrade was completed successfully and checks for common issues that might arise after an upgrade, such as duplicated dependencies, incompatible addons, or mismatched versions. -{/* prettier-ignore-start */} +The health check runs automatically for all detected Storybooks—no need to run it separately. - +### Error handling and debugging -{/* prettier-ignore-end */} +If you encounter issues during the upgrade: + +1. A `debug-storybook.log` file will be created containing all relevant logs +2. For more detailed information, set the log level to `trace` using the `--loglevel trace` flag +3. Create a GitHub issue with the logs if you need help resolving the problem + +## Command-line options + +The upgrade command supports several flags to customize the upgrade process: + +```bash +storybook@latest upgrade [options] +``` + +### Available flags + +| Flag | Description | +|------|-------------| +| `--disable-telemetry` | Disable sending telemetry data | +| `--debug` | Get more logs in debug mode (default: false) | +| `--enable-crash-reports` | Enable sending crash reports to telemetry data | +| `--write-logs` | Write all debug logs to a file at the end of the run | +| `--loglevel ` | Define log level: `trace`, `debug`, `info`, `warn`, `error`, or `silent` (default: "info") | +| `--package-manager ` | Force package manager: `npm`, `pnpm`, `yarn1`, `yarn2`, or `bun` | +| `-y, --yes` | Skip prompting the user | +| `-f, --force` | Force the upgrade, skipping autoblockers | +| `-s, --skip-check` | Skip postinstall version and automigration checks | +| `-c, --config-dir ` | Directory(ies) where to load Storybook configurations from | + +### Example usage + +```bash +# Upgrade with trace logging for debugging +storybook@latest upgrade --loglevel trace --write-logs + +# Force upgrade without prompts +storybook@latest upgrade --force --yes + +# Upgrade specific config directories only +storybook@latest upgrade --config-dir .storybook-frontend .storybook-backend +``` ## Automigrate script From 98596a78c385380fc2c46542384d1fad81334865 Mon Sep 17 00:00:00 2001 From: Valentin Palkovic Date: Wed, 11 Jun 2025 11:10:00 +0200 Subject: [PATCH 02/10] Docs: Clarify language --- docs/configure/upgrading.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index afe4a4d5520d..2f64d78d1015 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -42,7 +42,7 @@ The `upgrade` command will use whichever version you specify. For example: ### Mono-repository support -The upgrade script now provides enhanced support for mono-repositories: +The upgrade script provides enhanced support for mono-repositories: - **Automatic detection**: The script automatically detects all Storybook projects in your repository - **Selective upgrades**: If your Storybooks are truly encapsulated and don't share dependencies in shared `package.json` files, you can select which Storybook project to upgrade @@ -74,7 +74,7 @@ After running the command, the script will: ### Automatic health check -The upgrade script now automatically runs a health check on all detected Storybook projects after the upgrade. This verifies that the upgrade was completed successfully and checks for common issues that might arise after an upgrade, such as duplicated dependencies, incompatible addons, or mismatched versions. +The upgrade script automatically runs a health check on all detected Storybook projects after the upgrade. This verifies that the upgrade was completed successfully and checks for common issues that might arise after an upgrade, such as duplicated dependencies, incompatible addons, or mismatched versions. The health check runs automatically for all detected Storybooks—no need to run it separately. From f96845a89177fd351bd54b0f7f2e4f259830bcc7 Mon Sep 17 00:00:00 2001 From: Valentin Palkovic Date: Wed, 11 Jun 2025 11:10:56 +0200 Subject: [PATCH 03/10] Update docs/configure/upgrading.mdx Co-authored-by: Yann Braga --- docs/configure/upgrading.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index 2f64d78d1015..3f73798b82d3 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -83,7 +83,7 @@ The health check runs automatically for all detected Storybooks—no need to run If you encounter issues during the upgrade: 1. A `debug-storybook.log` file will be created containing all relevant logs -2. For more detailed information, set the log level to `trace` using the `--loglevel trace` flag +2. For more detailed information, set the log level to `debug` using the `--loglevel debug` flag 3. Create a GitHub issue with the logs if you need help resolving the problem ## Command-line options From 65530298eb1caa73477b43a07d17cc2af1b8fdc4 Mon Sep 17 00:00:00 2001 From: Valentin Palkovic Date: Wed, 11 Jun 2025 11:12:36 +0200 Subject: [PATCH 04/10] Update docs/configure/upgrading.mdx Co-authored-by: Yann Braga --- docs/configure/upgrading.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index 3f73798b82d3..721b58fa68d0 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -113,7 +113,7 @@ storybook@latest upgrade [options] ```bash # Upgrade with trace logging for debugging -storybook@latest upgrade --loglevel trace --write-logs +storybook@latest upgrade --loglevel debug --write-logs # Force upgrade without prompts storybook@latest upgrade --force --yes From 436da35f007a6523278143ab3d28f438f293d1e6 Mon Sep 17 00:00:00 2001 From: Valentin Palkovic Date: Wed, 11 Jun 2025 11:12:41 +0200 Subject: [PATCH 05/10] Update docs/configure/upgrading.mdx Co-authored-by: Yann Braga --- docs/configure/upgrading.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index 721b58fa68d0..efca9821808d 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -112,7 +112,7 @@ storybook@latest upgrade [options] ### Example usage ```bash -# Upgrade with trace logging for debugging +# Upgrade with debug logging for debugging storybook@latest upgrade --loglevel debug --write-logs # Force upgrade without prompts From 543fe433c265121b864d39d7db9d80d3f88cc647 Mon Sep 17 00:00:00 2001 From: Valentin Palkovic Date: Wed, 11 Jun 2025 11:12:16 +0200 Subject: [PATCH 06/10] Docs: Clarify selective upgrades in upgrading guide for mono-repositories --- docs/configure/upgrading.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index efca9821808d..0ffc0c2ffe09 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -45,7 +45,7 @@ The `upgrade` command will use whichever version you specify. For example: The upgrade script provides enhanced support for mono-repositories: - **Automatic detection**: The script automatically detects all Storybook projects in your repository -- **Selective upgrades**: If your Storybooks are truly encapsulated and don't share dependencies in shared `package.json` files, you can select which Storybook project to upgrade +- **Selective upgrades**: If your Storybooks are truly encapsulated (meaning each Storybook project has its own independent Storybook dependencies in its own `package.json`), you can select which Storybook project to upgrade - **Bulk upgrades**: If your Storybooks share dependencies, all detected projects will be upgraded together to ensure consistency ### Limiting scope in large mono-repositories From 9225c5ac225aa3d438bd48b8345c738aa466683f Mon Sep 17 00:00:00 2001 From: Valentin Palkovic Date: Wed, 11 Jun 2025 11:16:06 +0200 Subject: [PATCH 07/10] Docs: Add troubleshooting tips for custom Storybook configuration detection in upgrading guide --- docs/configure/upgrading.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index 0ffc0c2ffe09..b81f694576c6 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -170,4 +170,16 @@ If you'd like to downgrade to a stable version, manually edit the package versio {/* prettier-ignore-end */} + + ### Storybook doesn't detect my Storybook project + + If you don't use the standard Storybook convention of having a `.storybook` directory but rather you define a custom config directory, you can use the `--config-dir` flag to specify the directory where your Storybook configuration is located. + The `--config-dir` flag can be used multiple times to specify multiple directories. + + ```bash + storybook@latest upgrade --config-dir .storybook-frontend .storybook-backend + ``` + + If you're project can be detected but during the detection process you get an error, please watch out for the debug-storybook.log file in the root of your project. It will contain the full output of the detection process and will help you troubleshoot the issue. + From 2dfea87267fd0a2e84626dbc596bb9054c8dee78 Mon Sep 17 00:00:00 2001 From: Valentin Palkovic Date: Wed, 11 Jun 2025 11:18:23 +0200 Subject: [PATCH 08/10] Docs: Add note on manual migration of non-Storybook files in upgrading guide --- docs/configure/upgrading.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index b81f694576c6..f6310b0415ac 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -182,4 +182,9 @@ If you'd like to downgrade to a stable version, manually edit the package versio If you're project can be detected but during the detection process you get an error, please watch out for the debug-storybook.log file in the root of your project. It will contain the full output of the detection process and will help you troubleshoot the issue. + ### Storybook doesn't automigrate non-Storybook files + + Our automigrations usually only transform and migrate files inside of your `.storybook` directory and your story and mdx files, which are mentioned as part of the Storybook configuration. + If you have other files that contain Storybook-specific code, you might need to manually migrate them. + From 9648473ce2e1dc205d1719740dfa973f65191d69 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Thu, 12 Jun 2025 15:23:29 -0600 Subject: [PATCH 09/10] Tweaks --- docs/configure/upgrading.mdx | 74 +++++++++++++++++++----------------- 1 file changed, 40 insertions(+), 34 deletions(-) diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index f6310b0415ac..6a48d303e013 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -48,7 +48,7 @@ The upgrade script provides enhanced support for mono-repositories: - **Selective upgrades**: If your Storybooks are truly encapsulated (meaning each Storybook project has its own independent Storybook dependencies in its own `package.json`), you can select which Storybook project to upgrade - **Bulk upgrades**: If your Storybooks share dependencies, all detected projects will be upgraded together to ensure consistency -### Limiting scope in large mono-repositories +#### Limiting scope in large mono-repositories For large mono-repositories where you want to limit the upgrade to a specific directory, use the `STORYBOOK_PROJECT_ROOT` environment variable: @@ -76,13 +76,15 @@ After running the command, the script will: The upgrade script automatically runs a health check on all detected Storybook projects after the upgrade. This verifies that the upgrade was completed successfully and checks for common issues that might arise after an upgrade, such as duplicated dependencies, incompatible addons, or mismatched versions. -The health check runs automatically for all detected Storybooks—no need to run it separately. +The health check runs automatically for all detected Storybooks. You can also run it manually at any time using the `storybook doctor` command: + + ### Error handling and debugging If you encounter issues during the upgrade: -1. A `debug-storybook.log` file will be created containing all relevant logs +1. A `debug-storybook.log` file will be created in the repository root containing all relevant logs 2. For more detailed information, set the log level to `debug` using the `--loglevel debug` flag 3. Create a GitHub issue with the logs if you need help resolving the problem @@ -96,30 +98,30 @@ storybook@latest upgrade [options] ### Available flags -| Flag | Description | -|------|-------------| -| `--disable-telemetry` | Disable sending telemetry data | -| `--debug` | Get more logs in debug mode (default: false) | -| `--enable-crash-reports` | Enable sending crash reports to telemetry data | -| `--write-logs` | Write all debug logs to a file at the end of the run | -| `--loglevel ` | Define log level: `trace`, `debug`, `info`, `warn`, `error`, or `silent` (default: "info") | -| `--package-manager ` | Force package manager: `npm`, `pnpm`, `yarn1`, `yarn2`, or `bun` | -| `-y, --yes` | Skip prompting the user | -| `-f, --force` | Force the upgrade, skipping autoblockers | -| `-s, --skip-check` | Skip postinstall version and automigration checks | -| `-c, --config-dir ` | Directory(ies) where to load Storybook configurations from | +| Flag | Description | +| -------------------------------- | ------------------------------------------------------------------------------------------ | +| `-c, --config-dir ` | Directory or directories to find Storybook configurations | +| `--debug` | Enable more logs for debugging (default: false) | +| `--disable-telemetry` | Disable sending telemetry data | +| `--enable-crash-reports` | Enable sending crash reports to telemetry data | +| `-f, --force` | Force the upgrade, skipping autoblockers | +| `--loglevel ` | Define log level: `debug`, `error`, `info`, `silent`, `trace`, or `warn` (default: `info`) | +| `--package-manager ` | Force package manager: `npm`, `pnpm`, `yarn1`, `yarn2`, or `bun` | +| `-s, --skip-check` | Skip postinstall version and automigration checks | +| `--write-logs` | Write all debug logs to a file at the end of the run | +| `-y, --yes` | Skip prompting the user | ### Example usage ```bash -# Upgrade with debug logging for debugging +# Upgrade with logging for debugging storybook@latest upgrade --loglevel debug --write-logs # Force upgrade without prompts storybook@latest upgrade --force --yes # Upgrade specific config directories only -storybook@latest upgrade --config-dir .storybook-frontend .storybook-backend +storybook@latest upgrade --config-dir .storybook-app .storybook-ui ``` ## Automigrate script @@ -158,8 +160,28 @@ If you'd like to downgrade to a stable version, manually edit the package versio Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may [opt-out](../configure/telemetry.mdx#how-to-opt-out) if you'd not like to share any information. + +## Troubleshooting + +### Storybook doesn't detect my Storybook project + +By default, the upgrade script will attempt to find Storybook configuration in `.storybook` directories in your repository. If your Storybook configuration is located in a different directory, you can specify it using the `--config-dir` flag. + +The `--config-dir` flag can accept multiple directories. + +```bash +storybook@latest upgrade --config-dir .storybook-app .storybook-ui +``` + +If your project can be detected, but you get an error during the detection process, please check the `debug-storybook.log` file in the root of your repository. It will contain the full output of the detection process and will help you troubleshoot the issue. + +### Storybook doesn't automigrate non-Storybook files + +Our automigrations usually only transform and migrate files inside of your `.storybook` directory and your story and mdx files, which are mentioned as part of the Storybook configuration. + +If you have other files that contain Storybook-specific code, you might need to manually migrate them. + - ## Troubleshooting ### Storybook doesn't upgrade to the latest version when using Vue 2 @@ -171,20 +193,4 @@ If you'd like to downgrade to a stable version, manually edit the package versio {/* prettier-ignore-end */} - ### Storybook doesn't detect my Storybook project - - If you don't use the standard Storybook convention of having a `.storybook` directory but rather you define a custom config directory, you can use the `--config-dir` flag to specify the directory where your Storybook configuration is located. - The `--config-dir` flag can be used multiple times to specify multiple directories. - - ```bash - storybook@latest upgrade --config-dir .storybook-frontend .storybook-backend - ``` - - If you're project can be detected but during the detection process you get an error, please watch out for the debug-storybook.log file in the root of your project. It will contain the full output of the detection process and will help you troubleshoot the issue. - - ### Storybook doesn't automigrate non-Storybook files - - Our automigrations usually only transform and migrate files inside of your `.storybook` directory and your story and mdx files, which are mentioned as part of the Storybook configuration. - If you have other files that contain Storybook-specific code, you might need to manually migrate them. - From 9f4118c73582f6e56d6b2c7863fe1881c37fba40 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Thu, 12 Jun 2025 15:27:59 -0600 Subject: [PATCH 10/10] Update migration guide --- docs/migration-guide/index.mdx | 29 ++++++++++------------------- 1 file changed, 10 insertions(+), 19 deletions(-) diff --git a/docs/migration-guide/index.mdx b/docs/migration-guide/index.mdx index e31535402e11..336a9127cb21 100644 --- a/docs/migration-guide/index.mdx +++ b/docs/migration-guide/index.mdx @@ -56,7 +56,7 @@ You may wish to read the [full migration notes][full-migration-notes] before mig ## Automatic upgrade -To upgrade your Storybook: +To upgrade your Storybook, run the [upgrade](../configure/upgrading.mdx) command in the root of your repository: {/* prettier-ignore-start */} @@ -66,24 +66,15 @@ To upgrade your Storybook: This will: -1. Determine that none of the [breaking changes](#major-breaking-changes) apply to your project - * If they do, you will receive instructions on how to resolve them before continuing -2. Upgrade your Storybook dependencies to the latest version -3. Run a collection of *automigrations*, which will: - * Check for common upgrade tasks - * Explain the necessary changes with links to more information - * Ask for approval, then perform the task automatically on your behalf - - - -Migrating a monorepo project? Be sure to run the command in the current working directory (`cwd`) that contains the `storybook` package. - -Some helpful commands for monorepos: - -- For NX projects, you can use the `nx migrate` command -- The [`--config-dir` CLI flag](../api/cli-options.mdx#upgrade) can be used to specify a different config directory than the default `./.storybook` directory - - +1. Find all of the Storybook projects in your repository +2. For each project + 1. Determine that none of the [breaking changes](#major-breaking-changes) apply to your project + * If they do, you will receive instructions on how to resolve them before continuing + 2. Upgrade your Storybook dependencies to the latest version + 3. Run a collection of *automigrations*, which will: + * Check for common upgrade tasks + * Explain the necessary changes with links to more information + * Ask for approval, then perform the task automatically on your behalf ## New projects