From b23ccf1d263ce26900ae48d3c3331b54d09fa62f Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Fri, 12 Jan 2024 21:40:34 +0000 Subject: [PATCH 1/6] Docs: Adds commands to the documentation --- docs/addons/install-addons.md | 75 ++++++--- docs/api/cli-options.md | 143 +++++++++++++++++- docs/configure/upgrading.md | 26 +++- .../common/storybook-add-command.npm.js.mdx | 3 + .../common/storybook-add-command.pnpm.js.mdx | 3 + .../common/storybook-add-command.yarn.js.mdx | 3 + .../common/storybook-doctor.npm.js.mdx | 3 + .../common/storybook-doctor.pnpm.js.mdx | 3 + .../common/storybook-doctor.yarn.js.mdx | 3 + .../common/storybook-preset-scss.npm.js.mdx | 3 + .../common/storybook-preset-scss.pnpm.js.mdx | 3 + .../storybook-preset-scss.webpack-4.js.mdx | 10 -- .../storybook-preset-scss.webpack-5.js.mdx | 10 -- .../common/storybook-preset-scss.yarn.js.mdx | 3 + .../storybook-remove-command.npm.js.mdx | 3 + .../storybook-remove-command.pnpm.js.mdx | 3 + .../storybook-remove-command.yarn.js.mdx | 3 + 17 files changed, 252 insertions(+), 48 deletions(-) create mode 100644 docs/snippets/common/storybook-add-command.npm.js.mdx create mode 100644 docs/snippets/common/storybook-add-command.pnpm.js.mdx create mode 100644 docs/snippets/common/storybook-add-command.yarn.js.mdx create mode 100644 docs/snippets/common/storybook-doctor.npm.js.mdx create mode 100644 docs/snippets/common/storybook-doctor.pnpm.js.mdx create mode 100644 docs/snippets/common/storybook-doctor.yarn.js.mdx create mode 100644 docs/snippets/common/storybook-preset-scss.npm.js.mdx create mode 100644 docs/snippets/common/storybook-preset-scss.pnpm.js.mdx delete mode 100644 docs/snippets/common/storybook-preset-scss.webpack-4.js.mdx delete mode 100644 docs/snippets/common/storybook-preset-scss.webpack-5.js.mdx create mode 100644 docs/snippets/common/storybook-preset-scss.yarn.js.mdx create mode 100644 docs/snippets/common/storybook-remove-command.npm.js.mdx create mode 100644 docs/snippets/common/storybook-remove-command.pnpm.js.mdx create mode 100644 docs/snippets/common/storybook-remove-command.yarn.js.mdx diff --git a/docs/addons/install-addons.md b/docs/addons/install-addons.md index 33859546e2ea..43d6c167e372 100644 --- a/docs/addons/install-addons.md +++ b/docs/addons/install-addons.md @@ -2,13 +2,37 @@ title: 'Install addons' --- -Storybook has [hundreds of reusable addons](https://storybook.js.org/addons) that are packaged as NPM modules. Let's walk through how to extend Storybook by installing and registering addons. +Storybook has [hundreds of reusable addons](https://storybook.js.org/integrations) packaged as NPM modules. Let's walk through how to extend Storybook by installing and registering addons. -### Using addons +## Automatic installation -With the exception of preset addons, all addons have the same installation process: install and register. +Storybook includes a [`storybook add`](../api/cli-options.md#add) command to automate the setup of addons. Several community-led addons can be added using this command, except for preset addons. We encourage you to read the addon's documentation to learn more about its installation process. -For example, to include accessibility testing in Storybook, run the following command to install the necessary addon: +Run the `storybook add` command using your chosen package manager, and the CLI will update your Storybook configuration to include the addon and install any necessary dependencies. + + + + + + + + + +If you're attempting to install multiple addons at once, it will only install the first addon that was specified. This is a known limitation of the current implementation and will be addressed in a future release. + + + +### Manual installation + +Storybook addons are always added through the [`addons`](../api/main-config-addons.md) configuration array in [`.storybook/main.js|ts`](../configure/index.md). The following example shows how to manually add the [Accessibility addon](https://storybook.js.org/addons/@storybook/addon-a11y) to Storybook. + +Run the following command with your package manager of choice to install the addon. @@ -22,7 +46,7 @@ For example, to include accessibility testing in Storybook, run the following co -Next, update [`.storybook/main.js|ts`](../configure/index.md#configure-story-rendering) to the following: +Next, update `.storybook/main.js|ts` to the following: @@ -35,19 +59,29 @@ Next, update [`.storybook/main.js|ts`](../configure/index.md#configure-story-ren - +When you run Storybook, the accessibility testing addon will be enabled. -Addons may also require addon-specific configuration. Read their respective READMEs. +![Storybook addon installed and registered](./storybook-addon-installed-registered.png) - +### Removing addons -Now when you run Storybook the accessibility testing addon will be enabled. +To remove an addon from Storybook, you can choose to manually uninstall it and remove it from the configuration file (i.e., [`.storybook/main.js|ts`](../configure/index.md)) or opt-in to do it automatically via the CLI with the [`remove`](../api/cli-options.md#remove) command. For example, to remove the [Accessibility addon](https://storybook.js.org/addons/@storybook/addon-a11y) from Storybook with the CLI, run the following command: -![Storybook addon installed and registered](./storybook-addon-installed-registered.png) + + + + + -### Using preset addons +## Using preset addons -Storybook preset addons are grouped collections of specific `babel`, `webpack` and `addons` configurations for distinct use cases. Each one with its own set of instructions. Preset addons have a three-step installation process: install, register and optionally configuration. +Storybook preset addons are grouped collections of specific `babel`, `webpack` and `addons` configurations for distinct use cases. Each one has its own set of instructions. Preset addons have a three-step installation process: install, register, and optionally configure. For example, to use SCSS styling, run the following command to install the addon and the required dependencies: @@ -55,20 +89,21 @@ For example, to use SCSS styling, run the following command to install the addon - + -Use the Webpack 5 snippet only if your framework already includes support for this version. Otherwise, use the Webpack 4 snippet. +This preset addon is currently deprecated and no longer maintained. It's only mentioned here for example purposes. If you want to use SCSS styling in your project, we recommend using [@storybook/addon-styling-webpack](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) addon for Webpack based projects or the [@storybook/addon-themes](https://storybook.js.org/addons/@storybook/addon-themes) for a framework agnostic solution. -Next, update [`.storybook/main.js|ts`](../configure/index.md#configure-story-rendering) to the following: +Next, update [`.storybook/main.js|ts`](../configure/index.md) to the following: @@ -81,7 +116,7 @@ Next, update [`.storybook/main.js|ts`](../configure/index.md#configure-story-ren -Now when you run Storybook it will configure itself to use SCSS styling. No further configuration is needed. +When you run Storybook, it will configure itself to use SCSS styling. No further configuration is needed. #### Optional configuration @@ -105,8 +140,8 @@ Consider the following example: -Preset addons may also have addon-specific configurations. Read their respective READMEs. +Preset addons may also have addon-specific configurations. We encourage you to read their respective documentation to learn more about their configuration options. -Now, when Storybook starts up, it will update webpack's CSS loader to use modules and adjust how styling is defined. +When Storybook starts, it will update Webpack's CSS loader to use modules and adjust how styling is defined. diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index ee164e45e499..b0e48edc4e87 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 ### `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. +Compiles and serves as a development build of your Storybook that reflects your source code changes in the browser in real-time. It should be run from the root of your project. ```shell storybook dev [options] @@ -52,7 +52,7 @@ With the release of Storybook 8, the `-s` CLI flag was removed. We recommend usi ### `build` -Compiles your Storybook instance so it can be [deployed](../sharing/publish-storybook.md). Should be run from the root of your project. +Compile your Storybook instance so it can be [deployed](../sharing/publish-storybook.md). It should be run from the root of your project. ```shell storybook build [options] @@ -76,6 +76,143 @@ Options include: -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`. +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`. + + + +### `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` | + +### `doctor` + +**Added in:** Storybook 7.6 + +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` | + +### `upgrade` + +Upgrade your Storybook instance to the latest version. Read more in the [upgrade guide](../configure/upgrading.md). + +```shell +storybook upgrade [options] +``` + +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` | + +### `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 + Yarn: 1.22.21 - /usr/local/bin/yarn <----- active + npm: 10.2.3 - ~/.nvm/versions/node/v18.19.0/bin/npm + pnpm: 8.12.0 - /opt/homebrew/bin/pnpm + Browsers: + Chrome: 120.0.6099.199 + Safari: 17.2 + npmPackages: + @storybook/addon-a11y: ^7.6.6 => 7.6.6 + @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/server-webpack5: ^7.6.6 => 7.6.6 + @storybook/test: ^7.6.6 => 7.6.6 + @storybook/test-runner: ^0.16.0 => 0.16.0 + chromatic: ^10.2.0 => 10.2.0 + msw-storybook-addon: ^1.10.0 => 1.10.0 + storybook: ^7.6.6 => 7.6.6 +``` + +### `remove` + +**Added in:** Storybook 8.0 + +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` | + +### `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. + +```shell +storybook 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. + + + +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` | + + + +If you're looking for a hosted version of the available sandboxes, see [storybook.new](https://new-storybook.netlify.app/). diff --git a/docs/configure/upgrading.md b/docs/configure/upgrading.md index c5e57d8d714e..6de7c6c8af9a 100644 --- a/docs/configure/upgrading.md +++ b/docs/configure/upgrading.md @@ -6,7 +6,7 @@ The frontend ecosystem is a fast-moving place. Regular dependency upgrades are a ## Upgrade script -The most common upgrade is Storybook itself. [Storybook releases](https://storybook.js.org/releases) follow [Semantic Versioning](https://semver.org/). We publish patch releases with bug fixes continuously, minor versions of Storybook with new features every few months, and major versions of Storybook with breaking changes roughly once per year. +The most common upgrade is Storybook itself. [Storybook releases](https://storybook.js.org/releases) follow [Semantic Versioning](https://semver.org/). We publish patch releases with bug fixes continuously, minor versions of Storybook with new features every few months and major versions of Storybook with breaking changes roughly once per year. To help ease the pain of keeping Storybook up-to-date, we provide a command-line script: @@ -16,13 +16,13 @@ To help ease the pain of keeping Storybook up-to-date, we provide a command-line paths={[ 'common/storybook-upgrade.npm.js.mdx', 'common/storybook-upgrade.pnpm.js.mdx', - 'common/storybook-upgrade.yarn.js.mdx' + 'common/storybook-upgrade.yarn.js.mdx', ]} /> -After running the command the script will: +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 @@ -33,9 +33,25 @@ In addition to running the command, we also recommend checking the [MIGRATION.md +### Verifying the upgrade + +To help you verify that the upgrade was completed and that your project is still working as expected, the Storybook CLI provides the [`doctor`](../api/cli-options.md#doctor) command that allows you to do a health check on your project for common issues that might arise after an upgrade, such as duplicated dependencies, incompatible addons or mismatched versions. To perform the health check, run the following command with your package manager of choice: + + + + + + + ## Automigrate script -Storybook upgrades are not the only thing to consider: changes in the ecosystem also present challenges. For example, lots of frameworks ([Angular 12](https://angular.io/guide/updating-to-version-12#breaking-changes-in-angular-version-12), [Create React App v5](https://github.com/facebook/create-react-app/pull/11201), [NextJS](https://nextjs.org/docs/upgrading#webpack-5)) have recently migrated from [Webpack 4 to Webpack 5](https://webpack.js.org/migrate/5/), so even if you don't upgrade your Storybook version, you might need to update your configuration accordingly. That's what Automigrate is for: +Storybook upgrades are not the only thing to consider: changes in the ecosystem also present challenges. For example well-known frontend frameworks, such as [Angular](https://update.angular.io/?l=2&v=16.0-17.0), [Next.js](https://nextjs.org/docs/pages/building-your-application/upgrading) or [Svelte](https://svelte.dev/docs/v4-migration-guide) have been rolling out significant changes to their ecosystem, so even if you don't upgrade your Storybook version, you might need to update your configuration accordingly. That's what Automigrate is for: @@ -43,7 +59,7 @@ Storybook upgrades are not the only thing to consider: changes in the ecosystem paths={[ 'common/storybook-automigrate.npm.js.mdx', 'common/storybook-automigrate.pnpm.js.mdx', - 'common/storybook-automigrate.yarn.js.mdx' + 'common/storybook-automigrate.yarn.js.mdx', ]} /> diff --git a/docs/snippets/common/storybook-add-command.npm.js.mdx b/docs/snippets/common/storybook-add-command.npm.js.mdx new file mode 100644 index 000000000000..0218fa689fc4 --- /dev/null +++ b/docs/snippets/common/storybook-add-command.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npx storybook@latest add @storybook/addon-a11y +``` diff --git a/docs/snippets/common/storybook-add-command.pnpm.js.mdx b/docs/snippets/common/storybook-add-command.pnpm.js.mdx new file mode 100644 index 000000000000..14765e756e9f --- /dev/null +++ b/docs/snippets/common/storybook-add-command.pnpm.js.mdx @@ -0,0 +1,3 @@ +```shell +pnpm dlx storybook@latest add @storybook/addon-a11y +``` diff --git a/docs/snippets/common/storybook-add-command.yarn.js.mdx b/docs/snippets/common/storybook-add-command.yarn.js.mdx new file mode 100644 index 000000000000..bd0c2ea47953 --- /dev/null +++ b/docs/snippets/common/storybook-add-command.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn dlx storybook@latest add @storybook/addon-a11y +``` diff --git a/docs/snippets/common/storybook-doctor.npm.js.mdx b/docs/snippets/common/storybook-doctor.npm.js.mdx new file mode 100644 index 000000000000..be4a25ea91b2 --- /dev/null +++ b/docs/snippets/common/storybook-doctor.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npx storybook@latest doctor +``` diff --git a/docs/snippets/common/storybook-doctor.pnpm.js.mdx b/docs/snippets/common/storybook-doctor.pnpm.js.mdx new file mode 100644 index 000000000000..5db6170cc994 --- /dev/null +++ b/docs/snippets/common/storybook-doctor.pnpm.js.mdx @@ -0,0 +1,3 @@ +```shell +pnpm dlx storybook@latest doctor +``` diff --git a/docs/snippets/common/storybook-doctor.yarn.js.mdx b/docs/snippets/common/storybook-doctor.yarn.js.mdx new file mode 100644 index 000000000000..4561789bee6b --- /dev/null +++ b/docs/snippets/common/storybook-doctor.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn dlx storybook@latest doctor +``` diff --git a/docs/snippets/common/storybook-preset-scss.npm.js.mdx b/docs/snippets/common/storybook-preset-scss.npm.js.mdx new file mode 100644 index 000000000000..9c3e37d5a5d3 --- /dev/null +++ b/docs/snippets/common/storybook-preset-scss.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm install @storybook/preset-scss css-loader sass sass-loader style-loader --save-dev +``` diff --git a/docs/snippets/common/storybook-preset-scss.pnpm.js.mdx b/docs/snippets/common/storybook-preset-scss.pnpm.js.mdx new file mode 100644 index 000000000000..e895c7dead45 --- /dev/null +++ b/docs/snippets/common/storybook-preset-scss.pnpm.js.mdx @@ -0,0 +1,3 @@ +```shell +pnpm add --save-dev @storybook/preset-scss css-loader sass sass-loader style-loader +``` diff --git a/docs/snippets/common/storybook-preset-scss.webpack-4.js.mdx b/docs/snippets/common/storybook-preset-scss.webpack-4.js.mdx deleted file mode 100644 index 45c723540df1..000000000000 --- a/docs/snippets/common/storybook-preset-scss.webpack-4.js.mdx +++ /dev/null @@ -1,10 +0,0 @@ -```shell -# With npm -npm install @storybook/preset-scss css-loader@5.2.7 sass sass-loader@10.1.1 style-loader@2.0.0 --save-dev - -# With yarn -yarn add --dev @storybook/preset-scss css-loader@5.2.7 sass sass-loader@10.1.1 style-loader@2.0.0 - -# With pnpm -pnpm add --save-dev @storybook/preset-scss css-loader@5.2.7 sass sass-loader@10.1.1 style-loader@2.0.0 -``` diff --git a/docs/snippets/common/storybook-preset-scss.webpack-5.js.mdx b/docs/snippets/common/storybook-preset-scss.webpack-5.js.mdx deleted file mode 100644 index 276423fd25be..000000000000 --- a/docs/snippets/common/storybook-preset-scss.webpack-5.js.mdx +++ /dev/null @@ -1,10 +0,0 @@ -```shell -# With npm -npm install @storybook/preset-scss css-loader sass sass-loader style-loader --save-dev - -# With yarn -yarn add --dev @storybook/preset-scss css-loader sass sass-loader style-loader - -# With pnpm -pnpm add --save-dev @storybook/preset-scss css-loader sass sass-loader style-loader -``` diff --git a/docs/snippets/common/storybook-preset-scss.yarn.js.mdx b/docs/snippets/common/storybook-preset-scss.yarn.js.mdx new file mode 100644 index 000000000000..ac651bddfbe7 --- /dev/null +++ b/docs/snippets/common/storybook-preset-scss.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn add --dev @storybook/preset-scss css-loader sass sass-loader style-loader +``` diff --git a/docs/snippets/common/storybook-remove-command.npm.js.mdx b/docs/snippets/common/storybook-remove-command.npm.js.mdx new file mode 100644 index 000000000000..f27bdc549fd3 --- /dev/null +++ b/docs/snippets/common/storybook-remove-command.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npx storybook@latest remove @storybook/addon-a11y +``` diff --git a/docs/snippets/common/storybook-remove-command.pnpm.js.mdx b/docs/snippets/common/storybook-remove-command.pnpm.js.mdx new file mode 100644 index 000000000000..98734283c8a1 --- /dev/null +++ b/docs/snippets/common/storybook-remove-command.pnpm.js.mdx @@ -0,0 +1,3 @@ +```shell +pnpm dlx storybook@latest remove @storybook/addon-a11y +``` diff --git a/docs/snippets/common/storybook-remove-command.yarn.js.mdx b/docs/snippets/common/storybook-remove-command.yarn.js.mdx new file mode 100644 index 000000000000..a3cff8c18bd9 --- /dev/null +++ b/docs/snippets/common/storybook-remove-command.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn dlx storybook@latest remove @storybook/addon-a11y +``` From 1cc0ba0aac6302d06b896c55bf1e941dddb35ee8 Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Tue, 16 Jan 2024 15:44:07 +0000 Subject: [PATCH 2/6] Fixes link for storybook new --- docs/api/cli-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index b0e48edc4e87..8de9eee31e4c 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -213,6 +213,6 @@ Options include: -If you're looking for a hosted version of the available sandboxes, see [storybook.new](https://new-storybook.netlify.app/). +If you're looking for a hosted version of the available sandboxes, see [storybook.new](https://storybook.new). From fbf50c6721759e49525ba71daf9897d99ec82a8c Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Wed, 17 Jan 2024 14:19:38 +0000 Subject: [PATCH 3/6] Address feedback --- docs/addons/install-addons.md | 67 ------------------- docs/api/cli-options.md | 26 +++---- docs/configure/upgrading.md | 2 +- .../storybook-main-preset-config.js.mdx | 10 --- .../storybook-main-preset-config.ts.mdx | 14 ---- .../storybook-preset-configuration.js.mdx | 19 ------ .../storybook-preset-configuration.ts.mdx | 24 ------- .../common/storybook-preset-scss.npm.js.mdx | 3 - .../common/storybook-preset-scss.pnpm.js.mdx | 3 - .../common/storybook-preset-scss.yarn.js.mdx | 3 - 10 files changed, 10 insertions(+), 161 deletions(-) delete mode 100644 docs/snippets/common/storybook-main-preset-config.js.mdx delete mode 100644 docs/snippets/common/storybook-main-preset-config.ts.mdx delete mode 100644 docs/snippets/common/storybook-preset-configuration.js.mdx delete mode 100644 docs/snippets/common/storybook-preset-configuration.ts.mdx delete mode 100644 docs/snippets/common/storybook-preset-scss.npm.js.mdx delete mode 100644 docs/snippets/common/storybook-preset-scss.pnpm.js.mdx delete mode 100644 docs/snippets/common/storybook-preset-scss.yarn.js.mdx diff --git a/docs/addons/install-addons.md b/docs/addons/install-addons.md index 43d6c167e372..b12cc34e1186 100644 --- a/docs/addons/install-addons.md +++ b/docs/addons/install-addons.md @@ -78,70 +78,3 @@ To remove an addon from Storybook, you can choose to manually uninstall it and r /> - -## Using preset addons - -Storybook preset addons are grouped collections of specific `babel`, `webpack` and `addons` configurations for distinct use cases. Each one has its own set of instructions. Preset addons have a three-step installation process: install, register, and optionally configure. - -For example, to use SCSS styling, run the following command to install the addon and the required dependencies: - - - - - - - - - -This preset addon is currently deprecated and no longer maintained. It's only mentioned here for example purposes. If you want to use SCSS styling in your project, we recommend using [@storybook/addon-styling-webpack](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) addon for Webpack based projects or the [@storybook/addon-themes](https://storybook.js.org/addons/@storybook/addon-themes) for a framework agnostic solution. - - - -Next, update [`.storybook/main.js|ts`](../configure/index.md) to the following: - - - - - - - -When you run Storybook, it will configure itself to use SCSS styling. No further configuration is needed. - -#### Optional configuration - -Most preset addons can also take additional parameters. The most common use cases are: - -- Addon configuration -- Webpack loader configuration - -Consider the following example: - - - - - - - - - -Preset addons may also have addon-specific configurations. We encourage you to read their respective documentation to learn more about their configuration options. - - - -When Storybook starts, it will update Webpack's CSS loader to use modules and adjust how styling is defined. diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index 8de9eee31e4c..aa35a5befbf5 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -14,9 +14,15 @@ 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`. + + +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`. + + + ### `dev` -Compiles and serves as a development build of your Storybook that reflects your source code changes in the browser in real-time. It should be run from the root of your project. +Compiles and serves a development build of your Storybook that reflects your source code changes in the browser in real-time. It should be run from the root of your project. ```shell storybook dev [options] @@ -52,7 +58,7 @@ With the release of Storybook 8, the `-s` CLI flag was removed. We recommend usi ### `build` -Compile your Storybook instance so it can be [deployed](../sharing/publish-storybook.md). It should be run from the root of your project. +Compiles your Storybook instance so it can be [deployed](../sharing/publish-storybook.md). It should be run from the root of your project. ```shell storybook build [options] @@ -74,12 +80,6 @@ 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` | - - -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`. - - - ### `add` Installs a Storybook addon and configures your project for it. Read more in the [addon installation guide](../addons/install-addons.md). @@ -114,7 +114,7 @@ Options include: ### `upgrade` -Upgrade your Storybook instance to the latest version. Read more in the [upgrade guide](../configure/upgrading.md). +Upgrades your Storybook instance to the latest version. Read more in the [upgrade guide](../configure/upgrading.md). ```shell storybook upgrade [options] @@ -149,14 +149,10 @@ Storybook Environment Info: Shell: 5.9 - /bin/zsh Binaries: Node: 18.19.0 - ~/.nvm/versions/node/v18.19.0/bin/node - Yarn: 1.22.21 - /usr/local/bin/yarn <----- active npm: 10.2.3 - ~/.nvm/versions/node/v18.19.0/bin/npm - pnpm: 8.12.0 - /opt/homebrew/bin/pnpm Browsers: Chrome: 120.0.6099.199 - Safari: 17.2 npmPackages: - @storybook/addon-a11y: ^7.6.6 => 7.6.6 @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 @@ -165,11 +161,7 @@ Storybook Environment Info: @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/server-webpack5: ^7.6.6 => 7.6.6 @storybook/test: ^7.6.6 => 7.6.6 - @storybook/test-runner: ^0.16.0 => 0.16.0 - chromatic: ^10.2.0 => 10.2.0 - msw-storybook-addon: ^1.10.0 => 1.10.0 storybook: ^7.6.6 => 7.6.6 ``` diff --git a/docs/configure/upgrading.md b/docs/configure/upgrading.md index 6de7c6c8af9a..6f5a51e4545e 100644 --- a/docs/configure/upgrading.md +++ b/docs/configure/upgrading.md @@ -6,7 +6,7 @@ The frontend ecosystem is a fast-moving place. Regular dependency upgrades are a ## Upgrade script -The most common upgrade is Storybook itself. [Storybook releases](https://storybook.js.org/releases) follow [Semantic Versioning](https://semver.org/). We publish patch releases with bug fixes continuously, minor versions of Storybook with new features every few months and major versions of Storybook with breaking changes roughly once per year. +The most common upgrade is Storybook itself. [Storybook releases](https://storybook.js.org/releases) follow [Semantic Versioning](https://semver.org/). We publish patch releases with bug fixes continuously, minor versions of Storybook with new features every few months, and major versions of Storybook with breaking changes roughly once per year. To help ease the pain of keeping Storybook up-to-date, we provide a command-line script: diff --git a/docs/snippets/common/storybook-main-preset-config.js.mdx b/docs/snippets/common/storybook-main-preset-config.js.mdx deleted file mode 100644 index 20aedeebf98f..000000000000 --- a/docs/snippets/common/storybook-main-preset-config.js.mdx +++ /dev/null @@ -1,10 +0,0 @@ -```js -// .storybook/main.js - -export default { - // Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) - framework: '@storybook/your-framework', - stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], - addons: ['@storybook/preset-scss'], -}; -``` diff --git a/docs/snippets/common/storybook-main-preset-config.ts.mdx b/docs/snippets/common/storybook-main-preset-config.ts.mdx deleted file mode 100644 index ff07205c2bdd..000000000000 --- a/docs/snippets/common/storybook-main-preset-config.ts.mdx +++ /dev/null @@ -1,14 +0,0 @@ -```ts -// .storybook/main.ts - -// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) -import type { StorybookConfig } from '@storybook/your-framework'; - -const config: StorybookConfig = { - framework: '@storybook/your-framework', - stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], - addons: ['@storybook/preset-scss'], -}; - -export default config; -``` diff --git a/docs/snippets/common/storybook-preset-configuration.js.mdx b/docs/snippets/common/storybook-preset-configuration.js.mdx deleted file mode 100644 index d13ec2b360bf..000000000000 --- a/docs/snippets/common/storybook-preset-configuration.js.mdx +++ /dev/null @@ -1,19 +0,0 @@ -```js -// .storybook/main.js - -export default { - // Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) - framework: '@storybook/your-framework', - stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], - addons: [ - { - name: '@storybook/preset-scss', - options: { - cssLoaderOptions: { - modules: { localIdentName: '[name]__[local]--[hash:base64:5]' }, - }, - }, - }, - ], -}; -``` diff --git a/docs/snippets/common/storybook-preset-configuration.ts.mdx b/docs/snippets/common/storybook-preset-configuration.ts.mdx deleted file mode 100644 index 86cc4e9877a3..000000000000 --- a/docs/snippets/common/storybook-preset-configuration.ts.mdx +++ /dev/null @@ -1,24 +0,0 @@ -```ts -// .storybook/main.ts - -// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) -import type { StorybookConfig } from '@storybook/your-framework'; - -const config: StorybookConfig = { - // Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) - framework: '@storybook/your-framework', - stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], - addons: [ - { - name: '@storybook/preset-scss', - options: { - cssLoaderOptions: { - modules: { localIdentName: '[name]__[local]--[hash:base64:5]' }, - }, - }, - }, - ], -}; - -export default config; -``` diff --git a/docs/snippets/common/storybook-preset-scss.npm.js.mdx b/docs/snippets/common/storybook-preset-scss.npm.js.mdx deleted file mode 100644 index 9c3e37d5a5d3..000000000000 --- a/docs/snippets/common/storybook-preset-scss.npm.js.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```shell -npm install @storybook/preset-scss css-loader sass sass-loader style-loader --save-dev -``` diff --git a/docs/snippets/common/storybook-preset-scss.pnpm.js.mdx b/docs/snippets/common/storybook-preset-scss.pnpm.js.mdx deleted file mode 100644 index e895c7dead45..000000000000 --- a/docs/snippets/common/storybook-preset-scss.pnpm.js.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```shell -pnpm add --save-dev @storybook/preset-scss css-loader sass sass-loader style-loader -``` diff --git a/docs/snippets/common/storybook-preset-scss.yarn.js.mdx b/docs/snippets/common/storybook-preset-scss.yarn.js.mdx deleted file mode 100644 index ac651bddfbe7..000000000000 --- a/docs/snippets/common/storybook-preset-scss.yarn.js.mdx +++ /dev/null @@ -1,3 +0,0 @@ -```shell -yarn add --dev @storybook/preset-scss css-loader sass sass-loader style-loader -``` From cb22ad2a697406ca13db5141627162c8de197f23 Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Thu, 18 Jan 2024 13:52:15 +0000 Subject: [PATCH 4/6] Removes added notes --- docs/api/cli-options.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index aa35a5befbf5..02ea596f8889 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -97,8 +97,6 @@ Options include: ### `doctor` -**Added in:** Storybook 7.6 - 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 @@ -167,8 +165,6 @@ Storybook Environment Info: ### `remove` -**Added in:** Storybook 8.0 - Deletes a Storybook addon from your project. Read more in the [addon installation guide](../addons/install-addons.md#removing-addons). ```shell From e8dc7ca3ae2c5ebcbed03027f56004c5fbcc56ef Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Fri, 19 Jan 2024 11:32:36 +0000 Subject: [PATCH 5/6] change ordering of commands --- docs/api/cli-options.md | 78 +++++++++++++++++++++++++++-------------- 1 file changed, 51 insertions(+), 27 deletions(-) diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index 02ea596f8889..50e8454e2a26 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -80,6 +80,29 @@ 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 Storybook into your project per specified version (e.g., `@latest`, `@next`). Read more in the [installation guide](../get-started/install.md). + +```shell + +storybook[@version] init [options] +``` + +Options include: + +| Option | Description | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `-b`, `--builder` | Defines the [builder](../builders/index.md) to use for your Storybook
`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). @@ -95,20 +118,19 @@ Options include: | `--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` | -### `doctor` +### `remove` -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. +Deletes a Storybook addon from your project. Read more in the [addon installation guide](../addons/install-addons.md#removing-addons). ```shell -storybook doctor [options] +storybook remove [addon] [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` | +| 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` @@ -128,6 +150,21 @@ Options include: | `-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. @@ -147,7 +184,7 @@ Storybook Environment Info: 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 + npm: 10.2.3 - ~/.nvm/versions/node/v18.19.0/bin/npm <----- active Browsers: Chrome: 120.0.6099.199 npmPackages: @@ -161,22 +198,10 @@ Storybook Environment Info: @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 ``` -### `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` | - ### `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. @@ -193,11 +218,10 @@ The `framework-filter` argument is optional and can filter the list of available 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` | From 9fcfeb25f05769b4f16fc2455a9fa16e6fec1987 Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Fri, 19 Jan 2024 11:54:57 +0000 Subject: [PATCH 6/6] minor tweaks --- docs/api/cli-options.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/api/cli-options.md b/docs/api/cli-options.md index 50e8454e2a26..0f557786e813 100644 --- a/docs/api/cli-options.md +++ b/docs/api/cli-options.md @@ -87,7 +87,6 @@ Options include: Installs Storybook into your project per specified version (e.g., `@latest`, `@next`). Read more in the [installation guide](../get-started/install.md). ```shell - storybook[@version] init [options] ``` @@ -95,7 +94,7 @@ Options include: | Option | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `-b`, `--builder` | Defines the [builder](../builders/index.md) to use for your Storybook
`storybook init --builder webpack5` | +| `-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` |