diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index 1ccbb4d1f124..8b2a0f58cae3 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -14,6 +14,12 @@ Storybook collects completely anonymous data to help us improve user experience. All of the following documentation is available in the CLI by running `storybook --help`. + + +Passing options to these commands works slightly differently if you're using npm instead of Yarn. You must prefix all of your options with `--`. For example, `npm run storybook build -- -o ./path/to/build --quiet`. + + + ### `dev` Compiles and serves a development build of your Storybook that reflects your source code changes in the browser in real time. Should be run from the root of your project. @@ -76,8 +82,152 @@ Options include: | `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md).
`storybook build --disable-telemetry` | | `--test` | Optimize Storybook's production build for performance and tests by removing unnecessary features with the `test` option. Learn more [here](../api/main-config-build.md).
`storybook build --test` | - + + +### `init` + +Installs and initializes the specified version (e.g., `@latest`, `@8`, `@next`) of Storybook into your project. Read more in the [installation guide](../get-started/install.md). + +```shell +storybook[@version] init [options] +``` + +For example, `storybook@latest init` will install the latest version of Storybook into your project. + +Options include: + +| Option | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `-b`, `--builder` | Defines the [builder](../builders/index.md) to use for your Storybook instance
`storybook init --builder webpack5` | +| `-f`,`--force` | Forcefully installs Storybook into your project, prompting you to overwrite existing files
`storybook init --force` | +| `-s`, `--skip-install` | Skips the dependency installation step. Used only when you need to configure Storybook manually
`storybook init --skip-install` | +| `-t`, `--type` | Defines the [framework](../configure/frameworks.md) to use for your Storybook instance
`storybook init --type solid` | +| `-y`, `--yes` | Skips interactive prompts and automatically installs Storybook per specified version
`storybook init --yes` | +| `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook init --package-manager pnpm` | +| `--use-pnp` | Enables [Plug'n'Play](https://yarnpkg.com/features/pnp) support for Yarn. This option is only available when using Yarn as your package manager
`storybook init --use-pnp` | + +### `add` + +Installs a Storybook addon and configures your project for it. Read more in the [addon installation guide](../addons/install-addons.md). + +```shell +storybook add [addon] [options] +``` + +Options include: + +| Option | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook add [addon] --package-manager pnpm` | +| `-s`, `--skip-postinstall` | Skips post-install configuration. Used only when you need to configure the addon yourself
`storybook add [addon] --skip-postinstall` | + +### `remove` + +Deletes a Storybook addon from your project. Read more in the [addon installation guide](../addons/install-addons.md#removing-addons). + +```shell +storybook remove [addon] [options] +``` + +Options include: + +| Option | Description | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `--package-manager` | Sets the package manager to use when removing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook remove [addon]--package-manager pnpm` | + +### `upgrade` + +Upgrades your Storybook instance to the specified version (e.g., `@latest`, `@8`, `@next`). Read more in the [upgrade guide](../configure/upgrading.md). + +```shell +storybook[@version] upgrade [options] +``` + +For example, `storybook@latest upgrade --dry-run` will perform a dry run (no actual changes) of upgrading your project to the latest version of Storybook. + +Options include: + +| Option | Description | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`storybook upgrade --config-dir .storybook` | +| `-n`, `--dry-run` | Checks for version upgrades without installing them
`storybook upgrade --dry-run` | +| `-s`, `--skip-check` | Skips the migration check step during the upgrade process
`storybook upgrade --skip-check` | +| `-y`, `--yes` | Skips interactive prompts and automatically upgrades Storybook to the latest version
`storybook upgrade --yes` | +| `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook upgrade --package-manager pnpm` | + +### `doctor` + +Performs a health check on your Storybook project for common issues (e.g., duplicate dependencies, incompatible addons or mismatched versions) and provides suggestions on how to fix them. Applicable when [upgrading](../configure/upgrading.md#verifying-the-upgrade) Storybook versions. + +```shell +storybook doctor [options] +``` + +Options include: + +| Option | Description | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`storybook doctor --config-dir .storybook` | +| `--package-manager` | Sets the package manager to use when running the health check.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook doctor --package-manager pnpm` | + +### `info` + +Reports useful debugging information about your environment. Helpful in providing information when opening an issue or a discussion. + +```shell +storybook info +``` + +Example output: + +```shell +Storybook Environment Info: + + System: + OS: macOS 14.2 + CPU: (8) arm64 Apple M3 + Shell: 5.9 - /bin/zsh + Binaries: + Node: 18.19.0 - ~/.nvm/versions/node/v18.19.0/bin/node + npm: 10.2.3 - ~/.nvm/versions/node/v18.19.0/bin/npm <----- active + Browsers: + Chrome: 120.0.6099.199 + npmPackages: + @storybook/addon-essentials: ^7.6.6 => 7.6.6 + @storybook/addon-interactions: ^7.6.6 => 7.6.6 + @storybook/addon-links: ^7.6.6 => 7.6.6 + @storybook/addon-onboarding: ^1.0.10 => 1.0.10 + @storybook/blocks: ^7.6.6 => 7.6.6 + @storybook/preset-create-react-app: ^7.6.6 => 7.6.6 + @storybook/react: ^7.6.6 => 7.6.6 + @storybook/react-webpack5: ^7.6.6 => 7.6.6 + @storybook/test: ^7.6.6 => 7.6.6 + storybook: ^7.6.6 => 7.6.6 + npmGlobalPackages: + chromatic: ^10.2.0 => 10.2.0 +``` + +### `sandbox` + +Generates a local sandbox project using the specified version (e.g., `@latest`, `@8`, `@next`) for testing Storybook features based on the list of supported [frameworks](../configure/frameworks.md). Useful for reproducing bugs when opening an issue or a discussion. + +```shell +storybook[@version] sandbox [framework-filter] [options] +``` + +For example, `storybook@next sandbox` will generated sandboxes using the newest pre-release version of Storybook. + +The `framework-filter` argument is optional and can filter the list of available frameworks. For example, `storybook@next sandbox react` will only offer to generate React-based sandboxes. + +Options include: + +| Option | Description | +| --------------------------- | ---------------------------------------------------------------------------------------------------- | +| `-o`, `--output [dir-name]` | Configures the location of the sandbox project
`storybook sandbox --output /my-sandbox-project` | +| `--no-init` | Generates a sandbox project without without initializing Storybook
`storybook sandbox --no-init` | + + -If you're using npm instead of yarn to publish Storybook, the commands work slightly different. For example, `npm run storybook build -- -o ./path/to/build`. +If you're looking for a hosted version of the available sandboxes, see [storybook.new](https://storybook.new). diff --git a/docs/configure/upgrading.md b/docs/configure/upgrading.md index c5e57d8d714e..4ed46c2e6553 100644 --- a/docs/configure/upgrading.md +++ b/docs/configure/upgrading.md @@ -22,10 +22,16 @@ To help ease the pain of keeping Storybook up-to-date, we provide a command-line -After running the command the script will: +The `upgrade` command will use whichever version you specify. For example: -- Upgrade all Storybook packages in your project to the latest stable version -- Run the relevant [automigrations](../migration-guide.md#automatic-upgrade) factoring in the [breaking changes](../migration-guide.md#major-breaking-changes) between your current version and the latest stable version +- `storybook@latest upgrade` will upgrade to the latest version +- `storybook@7.6.10 upgrade` will upgrade to `7.6.10` +- `storybook@7 upgrade` will upgrade to the newest `7.x.x` version + +After running the command, the script will: + +- Upgrade all Storybook packages in your project to the specified version +- Run the relevant [automigrations](../migration-guide.md#automatic-upgrade) factoring in the [breaking changes](../migration-guide.md#major-breaking-changes) between your current version and the specified version @@ -69,6 +75,12 @@ To upgrade to the latest pre-release: +The `upgrade` command will use whichever version you specify. For example: + +- `storybook@next upgrade` will upgrade to the newest pre-release version +- `storybook@8.0.0-beta.1 upgrade` will upgrade to `8.0.0-beta.1` +- `storybook@8 upgrade` will upgrade to the newest `8.x` version + If you'd like to downgrade to a stable version, manually edit the package version numbers in your `package.json` and re-install. diff --git a/docs/get-started/install.md b/docs/get-started/install.md index 01ad6d3ff4e7..5053819c06f9 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -17,17 +17,13 @@ Use the Storybook CLI to install it in a single command. Run this inside your _e
+Install a specific version -storybook init is not made for empty projects +The `init` command will use whichever version you specify. For example: -Storybook needs to be installed into a project that is already set up with a framework. It will not work on an empty project. There are many ways to bootstrap an app in a given framework, including: - -- 📦 [Create an Angular Workspace](https://angular.io/cli/new) -- 📦 [Create React App](https://reactjs.org/docs/create-a-new-react-app.html) -- 📦 [Create a Vue App](https://vuejs.org/guide/quick-start.html) -- 📦 [Ember CLI](https://guides.emberjs.com/release/getting-started/quick-start/) -- 📦 [Vite CLI](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) -- Or any other tooling available. +- `storybook@latest init` will initialize the latest version +- `storybook@7.6.10 init` will initialize `7.6.10` +- `storybook@7 init` will initialize the newest `7.x.x` version
diff --git a/docs/snippets/common/storybook-upgrade-prerelease.npm.js.mdx b/docs/snippets/common/storybook-upgrade-prerelease.npm.js.mdx index 58a5cb6dd40c..2627dd4df0f9 100644 --- a/docs/snippets/common/storybook-upgrade-prerelease.npm.js.mdx +++ b/docs/snippets/common/storybook-upgrade-prerelease.npm.js.mdx @@ -1,3 +1,3 @@ ```shell -npx storybook@latest upgrade --prerelease +npx storybook@next upgrade ``` diff --git a/docs/snippets/common/storybook-upgrade-prerelease.pnpm.js.mdx b/docs/snippets/common/storybook-upgrade-prerelease.pnpm.js.mdx index 1e7199a4b8c3..0992b91d603b 100644 --- a/docs/snippets/common/storybook-upgrade-prerelease.pnpm.js.mdx +++ b/docs/snippets/common/storybook-upgrade-prerelease.pnpm.js.mdx @@ -1,3 +1,3 @@ ```shell -pnpm dlx storybook@latest upgrade --prerelease +pnpm dlx storybook@next upgrade ``` diff --git a/docs/snippets/common/storybook-upgrade-prerelease.yarn.js.mdx b/docs/snippets/common/storybook-upgrade-prerelease.yarn.js.mdx index 2033dc73e8dd..97f21c53a131 100644 --- a/docs/snippets/common/storybook-upgrade-prerelease.yarn.js.mdx +++ b/docs/snippets/common/storybook-upgrade-prerelease.yarn.js.mdx @@ -1,3 +1,3 @@ ```shell -yarn dlx storybook@latest upgrade --prerelease +yarn dlx storybook@next upgrade ```