From 56025448d9b7de241424c799e4caeb940d84dce4 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Thu, 18 Jan 2024 11:20:13 -0700 Subject: [PATCH] Document CLI version support --- docs/api/cli-options.md | 27 +++++++++---------- 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, 41 insertions(+), 19 deletions(-) diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index 02ea596f8889..8a0cf769f57c 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`. @@ -112,12 +112,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 | @@ -179,25 +181,22 @@ Options include: ### `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] ``` - - -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. +For example, `storybook@next sandbox react` will only offer to generate React-based sandboxes, using the newest pre-release version of Storybook. - +The `framework-filter` argument is optional and can filter the list of available frameworks. Options include: -| Option | Description | -| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-b`, `--branch [branch name]` | Select the branch to use for the sandbox project featuring the available features present in the selected branch (`next` for the pre-release version, `main` for the latest stable release)
`storybook sandbox --branch main` | -| `-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` | +| 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` | diff --git a/docs/configure/upgrading.md b/docs/configure/upgrading.md index 6f5a51e4545e..2880f1329dd7 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 44b2cf7aad92..e007e30e1838 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 ```