Node version requirement for Storybook contribution
Storybook requires Node version 18 to be installed. The suggested version is v18.16.0.
contributing/setup
20 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Windows terminal requirement for Storybook contribution
When working with Windows, all commands should be run in a terminal with administrator privileges.
Initial Storybook monorepo setup process
To set up the Storybook monorepo for contribution: first fork the repository on GitHub, then clone it locally with `git clone https://github.com/your-username/storybook.git` and navigate to the directory with `cd storybook`. Storybook uses Yarn as the package manager and Corepack to manage the correct version. Enable Corepack with `corepack enable`.
Getting started with Storybook contributions
Contributors unsure how to get started can chat in Discord in the #contributing channel, browse 'good first issues' to fix on the GitHub repository, or submit a bug report or feature request through GitHub issues.
Install Storybook command
Run the command 'npm create storybook@latest' to install Storybook into an existing project or create a new one from scratch.
Angular Storybook: run install at workspace root
To set up Storybook for an Angular project, run the install command at the root of the workspace where the angular.json file is located. This ensures that Storybook detects all projects correctly and creates the .storybook folder with proper angular.json configuration.
Module resolution: Yarn Plug-n-Play and monorepo environments
When using Yarn Plug-n-Play or in a monorepo environment, module resolution issues can occur with warnings like 'WARN Failed to load preset: "@storybook/react-webpack5/preset". Required package: @storybook/react-webpack5'. This can be fixed by wrapping the package name inside the Storybook configuration file (.storybook/main.js|ts).
Storybook upgrade command flags reference
The upgrade command supports these flags: `-c, --config-dir <dir-name...>` for directory or directories to find Storybook configurations; `--debug` to enable more logs for debugging (default: false); `--disable-telemetry` to disable sending telemetry data; `--enable-crash-reports` to enable sending crash reports; `-f, --force` to force the upgrade skipping autoblockers; `--loglevel <level>` to define log level (debug, error, info, silent, trace, or warn; default: info); `--package-manager <manager>` to force package manager (npm, pnpm, yarn1, yarn2, or bun); `-s, --skip-check` to skip postinstall version and automigration checks; `--logfile [path]` to write debug logs to a file (defaults to debug-storybook.log); `-y, --yes` to skip prompting the user.
Storybook automigrate command usage
Run `storybook automigrate` to handle configuration changes from ecosystem updates without upgrading Storybook itself. It runs a set of standard configuration checks, explains what is potentially out-of-date, and offers to fix it automatically while pointing to relevant documentation. This command runs automatically as part of `storybook upgrade` but is also available independently.
Storybook prerelease versions
Storybook publishes pre-release versions almost daily. Use `storybook@next upgrade` to upgrade to the newest pre-release version, or specify a specific pre-release like `storybook@8.0.0-beta.1 upgrade`. Pre-releases allow trying new features before general availability but may not be as stable as release versions.
Storybook automigration file scope limitations
Automigrations usually only transform files inside the `.storybook` directory and story and MDX files mentioned in the Storybook configuration. If you have other files containing Storybook-specific code outside these locations, you may need to manually migrate them.
Storybook release cadence
Storybook follows Semantic Versioning. Patch releases with bug fixes are published continuously, minor versions with new features are released every few months, and major versions with breaking changes are released roughly once per year.
Custom Storybook config directory detection
By default, the upgrade script searches for Storybook configuration in `.storybook` directories. If your configuration is in a different directory, use the `--config-dir` flag to specify one or multiple directories: `storybook@latest upgrade --config-dir .storybook-app .storybook-ui`.
MIGRATION.md file for upgrade details
After running the upgrade command, check the MIGRATION.md file in the Storybook repository for a detailed log of relevant changes and deprecations that might affect your upgrade.
Storybook upgrade command basic usage
Run `storybook@latest upgrade` from your repository root to automatically detect and upgrade all Storybook projects. The command automatically detects all Storybook projects in your repository, including in mono-repository setups.
Storybook version upgrade targets
The upgrade command accepts different version specifiers: `storybook@latest upgrade` upgrades to the latest version, `storybook@8.6.1 upgrade` upgrades to that specific version, and `storybook@9 upgrade` upgrades to the newest 9.x.x version.
Storybook upgrade command single major version limit
The upgrade command is designed to upgrade from one major version to the next only. Upgrading from Storybook 8 to 9 is supported, but upgrading from 7 to 9 is not. For multi-major upgrades, run the command multiple times sequentially. The only exception is upgrading from 6 to 8, which can be done directly with `storybook@8 upgrade`.
Mono-repository upgrade with STORYBOOK_PROJECT_ROOT
For large mono-repositories, use the `STORYBOOK_PROJECT_ROOT` environment variable to limit the upgrade to a specific directory: `STORYBOOK_PROJECT_ROOT=./packages/frontend storybook@latest upgrade`. This is helpful for huge mono-repositories with semi-encapsulated Storybooks.
Storybook upgrade process steps
After running the upgrade command, the script: detects all Storybook projects in your repository, upgrades all Storybook packages to the specified version, runs automigrations factoring in breaking changes between your current and target version, and automatically runs the doctor command to verify the upgrade.
Storybook doctor command for health checks
Run `storybook doctor` to perform a health check on all detected Storybook projects. This verifies that an upgrade was completed successfully and checks for common issues such as duplicated dependencies, incompatible addons, or mismatched versions. The health check runs automatically after upgrade but can also be run manually at any time.