From 2a3ef9a3d20f69c8dd449f6a5a45aab236d27f79 Mon Sep 17 00:00:00 2001 From: jonniebigodes Date: Tue, 31 May 2022 18:19:16 +0100 Subject: [PATCH] Updates to docs for better UX --- docs/addons/writing-addons.md | 19 ++++++++--- docs/builders/webpack.md | 34 ++++++++++++++----- docs/contribute/code.md | 20 ++++++----- docs/contribute/new-snippets.md | 8 +++-- docs/essentials/interactions.md | 15 ++++---- docs/essentials/introduction.md | 29 +++++++++------- docs/sharing/publish-storybook.md | 18 ++++++---- .../build-storybook-production-mode.js.mdx | 7 ---- ...build-storybook-production-mode.npm.js.mdx | 3 ++ ...uild-storybook-production-mode.yarn.js.mdx | 3 ++ .../common/chromatic-install.npm.js.mdx | 3 ++ .../common/chromatic-install.yarn.js.mdx | 3 ++ ...storybook-addon-actions-install.npm.js.mdx | 3 ++ ...torybook-addon-actions-install.yarn.js.mdx | 3 ++ ...rybook-addon-essentials-install.npm.js.mdx | 3 ++ ...ybook-addon-essentials-install.yarn.js.mdx | 3 ++ ...rybook-addon-storyshots-install.npm.js.mdx | 3 ++ ...ybook-addon-storyshots-install.yarn.js.mdx | 3 ++ .../storybook-debug-webpack-dev.npm.js.mdx | 3 ++ .../storybook-debug-webpack-dev.yarn.js.mdx | 3 ++ .../storybook-debug-webpack-prod.npm.js.mdx | 3 ++ .../storybook-debug-webpack-prod.yarn.js.mdx | 3 ++ ...rite-addon-install-dependencies.npm.js.mdx | 3 ++ ...ite-addon-install-dependencies.yarn.js.mdx | 3 ++ docs/writing-stories/play-function.md | 15 ++++---- docs/writing-tests/snapshot-testing.md | 15 ++++---- docs/writing-tests/visual-testing.md | 17 ++++++---- 27 files changed, 171 insertions(+), 74 deletions(-) delete mode 100644 docs/snippets/common/build-storybook-production-mode.js.mdx create mode 100644 docs/snippets/common/build-storybook-production-mode.npm.js.mdx create mode 100644 docs/snippets/common/build-storybook-production-mode.yarn.js.mdx create mode 100644 docs/snippets/common/chromatic-install.npm.js.mdx create mode 100644 docs/snippets/common/chromatic-install.yarn.js.mdx create mode 100644 docs/snippets/common/storybook-addon-actions-install.npm.js.mdx create mode 100644 docs/snippets/common/storybook-addon-actions-install.yarn.js.mdx create mode 100644 docs/snippets/common/storybook-addon-essentials-install.npm.js.mdx create mode 100644 docs/snippets/common/storybook-addon-essentials-install.yarn.js.mdx create mode 100644 docs/snippets/common/storybook-addon-storyshots-install.npm.js.mdx create mode 100644 docs/snippets/common/storybook-addon-storyshots-install.yarn.js.mdx create mode 100644 docs/snippets/common/storybook-debug-webpack-dev.npm.js.mdx create mode 100644 docs/snippets/common/storybook-debug-webpack-dev.yarn.js.mdx create mode 100644 docs/snippets/common/storybook-debug-webpack-prod.npm.js.mdx create mode 100644 docs/snippets/common/storybook-debug-webpack-prod.yarn.js.mdx create mode 100644 docs/snippets/common/storybook-write-addon-install-dependencies.npm.js.mdx create mode 100644 docs/snippets/common/storybook-write-addon-install-dependencies.yarn.js.mdx diff --git a/docs/addons/writing-addons.md b/docs/addons/writing-addons.md index 7b3079ad94a0..1be4af5d4454 100644 --- a/docs/addons/writing-addons.md +++ b/docs/addons/writing-addons.md @@ -50,13 +50,22 @@ Once you've gone through the prompts, your `package.json` should look like: ### Build system -We'll need to add the necessary dependencies and make some adjustments. Run the following commands: +We'll need to add the necessary dependencies and make some adjustments. Run the following command to install the required depedencies: -```shell -# Installs React and Babel CLI -yarn add react react-dom @babel/cli + -# Adds Storybook: + + + + +Initialize a local Storybook instance to allow you to test your addon. + +```shell npx sb init ``` diff --git a/docs/builders/webpack.md b/docs/builders/webpack.md index 768b4ab2ee9d..fa5568bb6c52 100644 --- a/docs/builders/webpack.md +++ b/docs/builders/webpack.md @@ -40,16 +40,34 @@ You can import `.json` files and have them expanded to a JavaScript object: -If you want to know the exact details of the Webpack config, the best way is to run either of the following: +If you want to know the exact details of the Webpack config, the best way is to run either of the following commands: -```shell +For development mode: -## Development mode -yarn start-storybook --debug-webpack + + + + + + +For production mode: -## Production mode -yarn build-storybook --debug-webpack -``` + + + + + + ### Code splitting @@ -199,5 +217,5 @@ When working with TypeScript projects, the default Webpack configuration may fai #### Learn more about builders - [Vite builder](./vite.md) for bundling with Vite -- [Webpack builder](./webpack.md) for bundling with Webpack +- Webpack builder for bundling with Webpack - [Builder API](./builder-api.md) for building a Storybook builder diff --git a/docs/contribute/code.md b/docs/contribute/code.md index 9a1f4fada5b6..f25714e4e713 100644 --- a/docs/contribute/code.md +++ b/docs/contribute/code.md @@ -6,13 +6,16 @@ Contribute a new feature or bug fix to [Storybook's monorepo](https://github.com ## Initial setup -First [fork](https://docs.github.com/en/github/getting-started-with-github/quickstart/fork-a-repo) the Storybook repository then clone and build your fork locally. Run the following commands: +Start by [forking](https://docs.github.com/en/github/getting-started-with-github/quickstart/fork-a-repo) the Storybook monorepo and cloning it locally. ```shell git clone https://github.com/your-username/storybook.git -cd storybook -yarn -yarn bootstrap --core +``` + +Navigate to the `storybook` directory and install the required dependencies with the following commands: + +```shell +yarn && yarn bootstrap --core ``` ## Run tests & examples @@ -28,8 +31,7 @@ yarn test Once the tests finish, check if the examples are working with the following commands: ```shell -cd examples/cra-ts-essentials -yarn storybook +cd examples/cra-ts-essentials && yarn storybook ```
@@ -106,7 +108,7 @@ Storybook's monorepo is set up to rely on end-to-end testing with [Cypress](http Before submitting your contribution, run the test suite one last time with: -```sh +```shell yarn test ``` @@ -133,7 +135,7 @@ We encourage bug reports to include reproductions. In the same way that it's pos To do so, run the following command in the root of the monorepo: -```sh +```shell npx sb@next link https://github.com/your-username/your-project.git ``` @@ -141,7 +143,7 @@ This command creates a project `../storybook-repros/your-project`, and automatic If you already have a reproduction on your local machine, you can similarly link it to your monorepo dev setup with the `--local` flag: -```sh +```shell npx sb@next link --local /path/to/local-repro-directory ``` diff --git a/docs/contribute/new-snippets.md b/docs/contribute/new-snippets.md index 84e4a91439b2..35a88ea36834 100644 --- a/docs/contribute/new-snippets.md +++ b/docs/contribute/new-snippets.md @@ -89,11 +89,15 @@ Go through the rest of the documentation and repeat the process. Before submitting your contribution, we advise you to check your work against the Storybook website. Doing this prevents last-minute issues with the documentation and is also an excellent way for the maintainers to merge faster once you submit the pull request. However, failing to do so will lead one of the maintainers to notify you that your contribution has an issue. -Start by forking [frontpage repo](https://github.com/storybookjs/frontpage). Then, clone and install the dependencies with the following commands: +Start by forking [frontpage repo](https://github.com/storybookjs/frontpage) and cloning it locally. ```shell git clone https://github.com/your-username/frontpage.git -cd frontpage +``` + +Navigate to the `frontpage` directory and install the required dependencies with the following command: + +```shell yarn ``` diff --git a/docs/essentials/interactions.md b/docs/essentials/interactions.md index 4e1ca5099177..a46bcc13b11a 100644 --- a/docs/essentials/interactions.md +++ b/docs/essentials/interactions.md @@ -18,13 +18,16 @@ The interactions are written using a Storybook-instrumented version of [Testing Since Interactions is still experimental, it doesn't yet ship with Storybook by default. As such, you'll have to install it. You may also want to add our wrappers for Testing Library and Jest. -```shell -# With npm -npm install @storybook/addon-interactions @storybook/jest @storybook/testing-library --save-dev + -# With yarn -yarn add --dev @storybook/addon-interactions @storybook/jest @storybook/testing-library -``` + + + Next, update [`.storybook/main.js`](../configure/overview.md#configure-story-rendering) to the following: diff --git a/docs/essentials/introduction.md b/docs/essentials/introduction.md index ea508ccb5411..bd2b6661e24d 100644 --- a/docs/essentials/introduction.md +++ b/docs/essentials/introduction.md @@ -18,13 +18,16 @@ If you ran `sb init` to include Storybook in your project, the Essentials addon If you're upgrading from a previous Storybook version, you'll need to run the following command in your terminal: -```shell -#With npm -npm install -D @storybook/addon-essentials + -#With yarn -yarn add -D @storybook/addon-essentials -``` + + + Update your Storybook configuration (in [`.storybook/main.js`](../configure/overview.md#configure-story-rendering)) to include the Essentials addon. @@ -44,14 +47,16 @@ Essentials is "zero-config”. It comes with a recommended configuration out of If you need to reconfigure any of the [individual Essentials addons](https://storybook.js.org/addons/tag/essentials), install them manually by following the installation instructions, register them in your Storybook configuration file (i.e., [`.storybook/main.js`](../configure/overview.md#configure-story-rendering)) and adjust the configuration to suit your needs. For example: -```shell -#With npm -npm install -D @storybook/addon-actions + + -#With yarn -yarn add -D @storybook/addon-actions -``` + diff --git a/docs/sharing/publish-storybook.md b/docs/sharing/publish-storybook.md index f260dc6f99aa..2e6794a0a923 100644 --- a/docs/sharing/publish-storybook.md +++ b/docs/sharing/publish-storybook.md @@ -21,7 +21,8 @@ First, we'll need to build Storybook as a static web application. The functional paths={[ 'angular/custom-build-script-production.script-for-builder.js.mdx', 'angular/build-storybook-production-mode.with-builder.js.mdx', - 'common/build-storybook-production-mode.js.mdx', + 'common/build-storybook-production-mode.yarn.js.mdx', + 'common/build-storybook-production-mode.npm.js.mdx', ]} /> @@ -49,13 +50,16 @@ To get started, sign up with your GitHub, GitLab, Bitbucket, or email and genera Next, install the [Chromatic CLI](https://www.npmjs.com/package/chromatic) package from npm: -```shell -# With npm -npm install --save-dev chromatic + -# With yarn -yarn add --dev chromatic -``` + + + Run the following command after the package finishes installing. Make sure that you replace `your-project-token` with your own project token. diff --git a/docs/snippets/common/build-storybook-production-mode.js.mdx b/docs/snippets/common/build-storybook-production-mode.js.mdx deleted file mode 100644 index 9bd298812fa9..000000000000 --- a/docs/snippets/common/build-storybook-production-mode.js.mdx +++ /dev/null @@ -1,7 +0,0 @@ -```shell -# With yarn -yarn build-storybook - -# With npm -npm run build-storybook -``` \ No newline at end of file diff --git a/docs/snippets/common/build-storybook-production-mode.npm.js.mdx b/docs/snippets/common/build-storybook-production-mode.npm.js.mdx new file mode 100644 index 000000000000..15ee902eae48 --- /dev/null +++ b/docs/snippets/common/build-storybook-production-mode.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm run build-storybook +``` \ No newline at end of file diff --git a/docs/snippets/common/build-storybook-production-mode.yarn.js.mdx b/docs/snippets/common/build-storybook-production-mode.yarn.js.mdx new file mode 100644 index 000000000000..eda3dbd3ad90 --- /dev/null +++ b/docs/snippets/common/build-storybook-production-mode.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn build-storybook +``` \ No newline at end of file diff --git a/docs/snippets/common/chromatic-install.npm.js.mdx b/docs/snippets/common/chromatic-install.npm.js.mdx new file mode 100644 index 000000000000..08f68adbfcc0 --- /dev/null +++ b/docs/snippets/common/chromatic-install.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm install chromatic --save-dev +``` \ No newline at end of file diff --git a/docs/snippets/common/chromatic-install.yarn.js.mdx b/docs/snippets/common/chromatic-install.yarn.js.mdx new file mode 100644 index 000000000000..ef2232eb8816 --- /dev/null +++ b/docs/snippets/common/chromatic-install.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn add --dev chromatic +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-addon-actions-install.npm.js.mdx b/docs/snippets/common/storybook-addon-actions-install.npm.js.mdx new file mode 100644 index 000000000000..a693fd458d6b --- /dev/null +++ b/docs/snippets/common/storybook-addon-actions-install.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm install @storybook/addon-actions --save-dev +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-addon-actions-install.yarn.js.mdx b/docs/snippets/common/storybook-addon-actions-install.yarn.js.mdx new file mode 100644 index 000000000000..b1e52357c623 --- /dev/null +++ b/docs/snippets/common/storybook-addon-actions-install.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn add --dev @storybook/addon-actions +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-addon-essentials-install.npm.js.mdx b/docs/snippets/common/storybook-addon-essentials-install.npm.js.mdx new file mode 100644 index 000000000000..a693fd458d6b --- /dev/null +++ b/docs/snippets/common/storybook-addon-essentials-install.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm install @storybook/addon-actions --save-dev +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-addon-essentials-install.yarn.js.mdx b/docs/snippets/common/storybook-addon-essentials-install.yarn.js.mdx new file mode 100644 index 000000000000..7bc9cf52e948 --- /dev/null +++ b/docs/snippets/common/storybook-addon-essentials-install.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn add --dev @storybook/addon-essentials +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-addon-storyshots-install.npm.js.mdx b/docs/snippets/common/storybook-addon-storyshots-install.npm.js.mdx new file mode 100644 index 000000000000..1d4b6caf3acc --- /dev/null +++ b/docs/snippets/common/storybook-addon-storyshots-install.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm install @storybook/addon-storyshots --save-dev +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-addon-storyshots-install.yarn.js.mdx b/docs/snippets/common/storybook-addon-storyshots-install.yarn.js.mdx new file mode 100644 index 000000000000..c847016ced68 --- /dev/null +++ b/docs/snippets/common/storybook-addon-storyshots-install.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn add --dev @storybook/addon-storyshots +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-debug-webpack-dev.npm.js.mdx b/docs/snippets/common/storybook-debug-webpack-dev.npm.js.mdx new file mode 100644 index 000000000000..080af4a1debf --- /dev/null +++ b/docs/snippets/common/storybook-debug-webpack-dev.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm run storybook -- --debug-webpack +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-debug-webpack-dev.yarn.js.mdx b/docs/snippets/common/storybook-debug-webpack-dev.yarn.js.mdx new file mode 100644 index 000000000000..8dbc7b2b49e4 --- /dev/null +++ b/docs/snippets/common/storybook-debug-webpack-dev.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn storybook --debug-webpack +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-debug-webpack-prod.npm.js.mdx b/docs/snippets/common/storybook-debug-webpack-prod.npm.js.mdx new file mode 100644 index 000000000000..5ca3edbb934f --- /dev/null +++ b/docs/snippets/common/storybook-debug-webpack-prod.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm run build-storybook -- --debug-webpack +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-debug-webpack-prod.yarn.js.mdx b/docs/snippets/common/storybook-debug-webpack-prod.yarn.js.mdx new file mode 100644 index 000000000000..1b2c9df57924 --- /dev/null +++ b/docs/snippets/common/storybook-debug-webpack-prod.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn build-storybook --debug-webpack +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-write-addon-install-dependencies.npm.js.mdx b/docs/snippets/common/storybook-write-addon-install-dependencies.npm.js.mdx new file mode 100644 index 000000000000..e196ab444371 --- /dev/null +++ b/docs/snippets/common/storybook-write-addon-install-dependencies.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm install react react-dom @babel/cli +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-write-addon-install-dependencies.yarn.js.mdx b/docs/snippets/common/storybook-write-addon-install-dependencies.yarn.js.mdx new file mode 100644 index 000000000000..e81984d3e2a2 --- /dev/null +++ b/docs/snippets/common/storybook-write-addon-install-dependencies.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn add react react-dom @babel/cli +``` \ No newline at end of file diff --git a/docs/writing-stories/play-function.md b/docs/writing-stories/play-function.md index cef5c1be9920..0923ee57a2c3 100644 --- a/docs/writing-stories/play-function.md +++ b/docs/writing-stories/play-function.md @@ -10,13 +10,16 @@ We recommend installing Storybook's [`addon-interactions`](https://storybook.js. Run the following command to install the addon and the required dependencies. -```shell -# With npm -npm install @storybook/addon-interactions @storybook/testing-library --save-dev + -# With yarn -yarn add --dev @storybook/addon-interactions @storybook/testing-library -``` + + + Update your Storybook configuration (in `.storybook/main.js`) to include the interactions addon. diff --git a/docs/writing-tests/snapshot-testing.md b/docs/writing-tests/snapshot-testing.md index 242c1f00885f..1b90a05dfec7 100644 --- a/docs/writing-tests/snapshot-testing.md +++ b/docs/writing-tests/snapshot-testing.md @@ -14,13 +14,16 @@ Storybook is a helpful tool for snapshot testing because every story is essentia Run the following command to install Storyshots: -```shell -# With npm -npm install @storybook/addon-storyshots --save-dev + -# With yarn -yarn add --dev @storybook/addon-storyshots -``` + + + Add a test file to your environment with the following contents to configure Storyshots: diff --git a/docs/writing-tests/visual-testing.md b/docs/writing-tests/visual-testing.md index a5336a3854a0..bed00fbfcffb 100644 --- a/docs/writing-tests/visual-testing.md +++ b/docs/writing-tests/visual-testing.md @@ -20,13 +20,18 @@ To get started, sign up with your [GitHub](https://github.com/), [GitLab](https: Next, install the [chromatic](https://www.npmjs.com/package/chromatic) CLI package from npm: -```shell -# With npm -npm install chromatic --save-dev + + + + + + -# With yarn -yarn add --dev chromatic -``` Run the following command after the package finishes installing: