From 5c2759b8e3c71a6e518c7e5a15f29cd59c2f16dd Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Mon, 22 Jan 2024 10:39:33 -0700 Subject: [PATCH] Document CLI version support --- docs/api/cli-options.md | 22 ++++++++++--------- docs/configure/upgrading.md | 16 ++++++++++++-- docs/get-started/install.md | 11 ++++++++++ .../storybook-upgrade-prerelease.npm.js.mdx | 2 +- .../storybook-upgrade-prerelease.pnpm.js.mdx | 2 +- .../storybook-upgrade-prerelease.yarn.js.mdx | 2 +- 6 files changed, 40 insertions(+), 15 deletions(-) diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index 0f557786e813..ad8292dfad31 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -16,7 +16,7 @@ All of the following documentation is available in the CLI by running `storybook -The commands work slightly differently if you're using npm instead of Yarn to publish Storybook. For example, `npm run storybook build -- -o ./path/to/build`. +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`. @@ -84,12 +84,14 @@ Options include: ### `init` -Installs Storybook into your project per specified version (e.g., `@latest`, `@next`). Read more in the [installation guide](../get-started/install.md). +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 | @@ -133,12 +135,14 @@ Options include: ### `upgrade` -Upgrades your Storybook instance to the latest version. Read more in the [upgrade guide](../configure/upgrading.md). +Upgrades your Storybook instance to the specified version (e.g., `@latest`, `@8`, `@next`). Read more in the [upgrade guide](../configure/upgrading.md). ```shell -storybook upgrade [options] +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 | @@ -203,17 +207,15 @@ Storybook Environment Info: ### `sandbox` -Generates a local sandbox project 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. +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 sandbox [framework-filter] [options] +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 sandbox react` will only show React-based sandboxes. - - +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: diff --git a/docs/configure/upgrading.md b/docs/configure/upgrading.md index 23f10948b218..c29b34b86ed8 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 +The `upgrade` command will use whichever version you specify. For example: + +- `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 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 +- 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 @@ -85,6 +91,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 71b7800fa4a7..a0fd39720cd0 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -16,6 +16,17 @@ Use the Storybook CLI to install it in a single command. Run this inside your pr +
+Install a specific version + +The `init` command will use whichever version you specify. For example: + +- `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 + +
+ Storybook will look into your project's dependencies during its install process and provide you with the best configuration available. The command above will make the following changes to your local environment: 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 ```