Merge pull request #25658 from storybookjs/docs-cli-versioning

Docs: Document CLI version support (cherry picked from commit 7bbf75f)
storybookjs · Jan 31, 2024 · 81561cd · 81561cd
1 parent dc4437b
commit 81561cd
Show file tree

Hide file tree

Showing 6 changed files with 175 additions and 17 deletions.
diff --git 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`.
 
+<Callout variant="info" icon="💡">
+
+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`.
+
+</Callout>
+
 ### `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).<br/>`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).<br/>`storybook build --test` |
 
-<Callout variant="info" icon="💡">
+<!-- Re-read this for accuracy -->
+
+### `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<br/>`storybook init --builder webpack5`                                                         |
+| `-f`,`--force`         | Forcefully installs Storybook into your project, prompting you to overwrite existing files<br/>`storybook init --force`                                                        |
+| `-s`, `--skip-install` | Skips the dependency installation step. Used only when you need to configure Storybook manually<br/>`storybook init --skip-install`                                            |
+| `-t`, `--type`         | Defines the [framework](../configure/frameworks.md) to use for your Storybook instance<br/>`storybook init --type solid`                                                       |
+| `-y`, `--yes`          | Skips interactive prompts and automatically installs Storybook per specified version<br/>`storybook init --yes`                                                                |
+| `--package-manager`    | Sets the package manager to use when installing the addon.<br/> Available package managers include `npm`, `yarn`, and `pnpm`<br/>`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<br/>`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.<br/> Available package managers include `npm`, `yarn`, and `pnpm`<br/>`storybook add [addon] --package-manager pnpm` |
+| `-s`, `--skip-postinstall` | Skips post-install configuration. Used only when you need to configure the addon yourself<br/>`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.<br/>Available package managers include `npm`, `yarn`, and `pnpm`<br/>`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<br/>`storybook upgrade --config-dir .storybook`                                                                       |
+| `-n`, `--dry-run`    | Checks for version upgrades without installing them<br/>`storybook upgrade --dry-run`                                                                                       |
+| `-s`, `--skip-check` | Skips the migration check step during the upgrade process<br/> `storybook upgrade --skip-check`                                                                             |
+| `-y`, `--yes`        | Skips interactive prompts and automatically upgrades Storybook to the latest version<br/>`storybook upgrade --yes`                                                          |
+| `--package-manager`  | Sets the package manager to use when installing the addon.<br/> Available package managers include `npm`, `yarn`, and `pnpm`<br/>`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<br/>`storybook doctor --config-dir .storybook`                                                                          |
+| `--package-manager`  | Sets the package manager to use when running the health check.<br/>Available package managers include `npm`, `yarn`, and `pnpm`<br/>`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<br/>`storybook sandbox --output /my-sandbox-project`  |
+| `--no-init`                 | Generates a sandbox project without without initializing Storybook<br/>`storybook sandbox --no-init` |
+
+<Callout variant="info">
 
-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).
 
 </Callout>
diff --git 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
 
 <!-- prettier-ignore-end -->
 
-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
 
 <Callout variant="info">
 
@@ -69,6 +75,12 @@ To upgrade to the latest pre-release:
 
 <!-- prettier-ignore-end -->
 
+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.
 
 <Callout variant="info">

diff --git 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
 <!-- prettier-ignore-end -->
 
 <details>
+<summary>Install a specific version</summary>
 
-<summary><code>storybook init</code> is not made for empty projects</summary>
+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
 
 </details>
 

diff --git 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
@@ -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
@@ -1,3 +1,3 @@
 ```shell
-yarn dlx storybook@latest upgrade --prerelease
+yarn dlx storybook@next upgrade
 ```