diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index 8bce398476d4e..8f5ac428da5b9 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -5907,6 +5907,14 @@ "isExternal": false, "children": [], "disableCollapsible": false + }, + { + "name": "Custom configurations for Webpack and Vite", + "path": "/packages/storybook/documents/custom-builder-configs", + "id": "custom-builder-configs", + "isExternal": false, + "children": [], + "disableCollapsible": false } ], "isExternal": false, diff --git a/docs/generated/manifests/packages.json b/docs/generated/manifests/packages.json index 5ef49adcb76ac..81197f0a0895d 100644 --- a/docs/generated/manifests/packages.json +++ b/docs/generated/manifests/packages.json @@ -2521,6 +2521,17 @@ "path": "/packages/storybook/documents/upgrade-storybook-v6-react", "tags": [], "originalFilePath": "shared/packages/storybook/storybook-v6-react" + }, + "/packages/storybook/documents/custom-builder-configs": { + "id": "custom-builder-configs", + "name": "Custom configurations for Webpack and Vite", + "description": "The Nx Plugin for Storybook contains executors and generators for allowing your workspace to use the powerful Storybook integration testing & documenting capabilities.", + "file": "generated/packages/storybook/documents/custom-builder-configs", + "itemList": [], + "isExternal": false, + "path": "/packages/storybook/documents/custom-builder-configs", + "tags": [], + "originalFilePath": "shared/packages/storybook/custom-builder-configs" } }, "root": "/packages/storybook", diff --git a/docs/generated/packages-metadata.json b/docs/generated/packages-metadata.json index 1819f31a731e1..1f1d3bce6ab45 100644 --- a/docs/generated/packages-metadata.json +++ b/docs/generated/packages-metadata.json @@ -2494,6 +2494,17 @@ "path": "storybook/documents/upgrade-storybook-v6-react", "tags": [], "originalFilePath": "shared/packages/storybook/storybook-v6-react" + }, + { + "id": "custom-builder-configs", + "name": "Custom configurations for Webpack and Vite", + "description": "The Nx Plugin for Storybook contains executors and generators for allowing your workspace to use the powerful Storybook integration testing & documenting capabilities.", + "file": "generated/packages/storybook/documents/custom-builder-configs", + "itemList": [], + "isExternal": false, + "path": "storybook/documents/custom-builder-configs", + "tags": [], + "originalFilePath": "shared/packages/storybook/custom-builder-configs" } ], "executors": [ diff --git a/docs/generated/packages/storybook/documents/custom-builder-configs.md b/docs/generated/packages/storybook/documents/custom-builder-configs.md new file mode 100644 index 0000000000000..06b582a0bd43d --- /dev/null +++ b/docs/generated/packages/storybook/documents/custom-builder-configs.md @@ -0,0 +1,143 @@ +# Custom configurations for Webpack and Vite + +Storybook allows you to customize the `webpack` configuration and your `vite` configuration. For that, it offers two fields you can add in your `.storybook/main.js|ts` file, called `webpackFinal` and `viteFinal`. These fields are functions that take the default configuration as an argument, and return the modified configuration. You can read more about them in the [Storybook documentation for `webpack`](https://storybook.js.org/docs/react/builders/webpack#extending-storybooks-webpack-config) and the [Storybook documentation for `vite`](https://storybook.js.org/docs/react/builders/vite#configuration). + +You can use these fields in your Nx workspace Storybook configurations normally, following the Storybook docs. However, let's see how you can create a global configuration for every project in your workspace, and how you can override it for specific projects. + +## Global configuration + +In your root `.storybook/main.js|ts` file, you can add the `webpackFinal` or `viteFinal` field, and return the modified configuration. This will be applied to every project in your workspace. + +### `webpack` and `webpackFinal` + +The `webpackFinal` field would look like this: + +```ts +webpackFinal: async (config, { configType }) => { + // Make whatever fine-grained changes you need that should apply to all storybook configs + + // Return the altered config + return config; +}, +``` + +### `vite` and `viteFinal` + +The `viteFinal` field would look like this: + +```ts +async viteFinal(config, { configType }) { + if (configType === 'DEVELOPMENT') { + // Your development configuration goes here + } + if (configType === 'PRODUCTION') { + // Your production configuration goes here. + } + return mergeConfig(config, { + // Your environment configuration here + }); + }, +``` + +In the `viteFinal` case, you would have to import the `mergeConfig` function from `vite`. So, on the top of your root `.storybook/main.js|ts` file, you would have to add: + +```ts +const { mergeConfig } = require('vite'); +``` + +## Project-specific configuration + +### `webpack` and `webpackFinal` + +You can customize or extend the global `webpack` configuration for a specific project by adding a `webpackFinal` field in your project-specific `.storybok/main.js|ts` file, like this: + +```ts +// apps/my-react-webpack-app/.storybook/main.js + +const rootMain = require('../../../.storybook/main'); + +module.exports = { + ...rootMain, + ... + webpackFinal: async (config, { configType }) => { + // apply any global webpack configs that might have been specified in .storybook/main.js + if (rootMain.webpackFinal) { + config = await rootMain.webpackFinal(config, { configType }); + } + + // add your own webpack tweaks if needed + + return config; + }, +}; +``` + +Take note how we are first applying the global `webpack` configuration, and then adding our own tweaks. If you don't want to apply any global configuration, you can just return your own configuration, and skip the `rootMain.webpackFinal` check. + +### `vite` and `viteFinal` + +You can customize or extend the global `vite` configuration for a specific project by adding a `viteFinal` field in your project-specific `.storybok/main.js|ts` file. + +{% callout type="check" title="Don't forget the vite-tsconfig-paths plugin" %} +For Vite.js to work on monorepos, and specifically on Nx workspaces, you need to use the `'vite-tsconfig-paths'` plugin! +{% /callout %} + +It's important to note here that for Vite.js to work on monorepos, and specifically on Nx workspaces, you need to use the `'vite-tsconfig-paths'` plugin, just like you must already do in your project's `vite.config.ts` file. Storybook does not read your project's Vite configuration automatically, so you have to manually add the plugin to your project's Storybook Vite configuration. + +So, a project-level `.storybook/main.js|ts` file for a Vite.js project would look like this: + +```ts +// apps/my-react-vite-app/.storybook/main.js +const { mergeConfig } = require('vite'); +const viteTsConfigPaths = require('vite-tsconfig-paths').default; +const rootMain = require('../../../.storybook/main'); + +module.exports = { + ...rootMain, + core: { ...rootMain.core, builder: '@storybook/builder-vite' }, + stories: [ + ...rootMain.stories, + '../src/app/**/*.stories.mdx', + '../src/app/**/*.stories.@(js|jsx|ts|tsx)', + ], + addons: [...rootMain.addons], + async viteFinal(config, { configType }) { + return mergeConfig(config, { + ...((await rootMain.viteFinal(config, { configType })) ?? {}), + plugins: [ + viteTsConfigPaths({ + root: '../../../', + }), + ], + }); + }, +}; +``` + +or just simplified (if you don't want to take into account any global Storybook Vite.js configuration): + +```ts +const { mergeConfig } = require('vite'); +const viteTsConfigPaths = require('vite-tsconfig-paths').default; +const rootMain = require('../../../.storybook/main'); + +module.exports = { + ...rootMain, + core: { ...rootMain.core, builder: '@storybook/builder-vite' }, + stories: [ + ...rootMain.stories, + '../src/app/**/*.stories.mdx', + '../src/app/**/*.stories.@(js|jsx|ts|tsx)', + ], + addons: [...rootMain.addons], + async viteFinal(config, { configType }) { + return mergeConfig(config, { + plugins: [ + viteTsConfigPaths({ + root: '../../../', + }), + ], + }); + }, +}; +``` diff --git a/docs/generated/packages/storybook/documents/migrate-storybook-7.md b/docs/generated/packages/storybook/documents/migrate-storybook-7.md index e63fc33afef17..1d74ffe95aee6 100644 --- a/docs/generated/packages/storybook/documents/migrate-storybook-7.md +++ b/docs/generated/packages/storybook/documents/migrate-storybook-7.md @@ -1,25 +1,29 @@ -# Migrate to Storybook to version 7 +# Migrate your Nx workspace to Storybook version 7 + +{% callout type="info" title="Available on Nx v15.5" %} +This is a new feature available on Nx v15.5.0. If you are using an older version of Nx, please [upgrade](/packages/nx/documents/migrate). +{% /callout %} {% callout type="warning" title="Storybook 7 is in beta" %} -[Storybook version 7 is still in beta](https://storybook.js.org/blog/7-0-beta/). Things are evolving dynamically, so it would be better to _avoid using in production_. If you want to use the stable, [6.5 version](https://storybook.js.org/releases/6.5), please go to the [Storybook plugin overview guide](/packages/storybook) to get started. +[Storybook version 7 is still in beta](https://storybook.js.org/blog/7-0-beta/), and so is the Nx support for it. Things are evolving dynamically, so it would be better to _avoid using in production_ on Nx. If you want to use the stable, [6.5 version](https://storybook.js.org/releases/6.5), please go to the [Storybook plugin overview guide](/packages/storybook) to get started. {% /callout %} {% callout type="info" title="Setting up Storybook 7 in a new workspace" %} -For settin up Storybook version 7 in a new Nx workspace, or a workspace that does NOT already have Storybook configured already, please refer to our [Storybook 7 setup guide](/packages/storybook/documents/storybook-7-setup). +For setting up Storybook version 7 in a new Nx workspace, or a workspace that does NOT already have Storybook configured already, please refer to our [Storybook 7 setup guide](/packages/storybook/documents/storybook-7-setup). {% /callout %} -Storybook 7 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 7 beta announcement blog post](https://storybook.js.org/blog/7-0-beta/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 7 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). Do note that _version 7 is still in beta_, and things are evolving dynamically, so it would be better to _avoid using in production_. +Storybook 7 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 7 beta announcement blog post](https://storybook.js.org/blog/7-0-beta/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 7 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). Do note that _version 7 is still in beta_, and so is the Nx support for it. Things are evolving dynamically, so it would be better to _avoid using in production_ on Nx. You can now migrate your existing Nx workspace with Storybook configuration to use Storybook version 7. This guide will show you how to do that. ## Use the Storybook CLI to upgrade -You can take advantage of the Storybook CLI to automatically migrate some settings of your Storybook setup. For a full guide to migration using the Storybook CLI, please refer to the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). +You can take advantage of the Storybook CLI to automatically migrate some settings of your Storybook setup on your Nx workspace. For a full guide to migration using the Storybook CLI, please refer to the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). -The Storybook migration scripts do not work perfectly with Nx, however we can use them to get the latest beta versions of our packages, remove some unused packages, and get a hint of some settings that we will need to change manually, eventually. +The Storybook migration scripts do not work perfectly on Nx workspaces, however we can use them to get the latest beta versions of our packages, remove some unused packages and get a hint of some settings that we will need to change manually, eventually. {% callout type="warning" title="Don't use in production" %} -Please take extra care when migrating your existing Storybook setup to version 7. Do not use in production, since it's still in beta. +Please take extra care when migrating your existing Storybook setup to version 7 on your Nx workspace. Do not use in production, since it's still in beta, and the Nx support is not stable yet. {% /callout %} Let's see the steps we can make to migrate our Storybook setup to version 7. @@ -37,24 +41,24 @@ This will: For more info, see [here](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). -### 2. Click yes to the automigration prompts +### 2. Say `yes` to the automigration prompts The Storybook CLI will prompt you to run some code generators and modifiers. -Click `yes` to the following: +Say `yes` to the following: - `mainjsFramework`: It will add the `framework` field in your root `.storybook/main.js|ts` file. We are going to delete it since it's not needed in the root file, but it's handy to have it ready to copy. Also, it shows you an indication of what it looks like. - `eslintPlugin`: installs the `eslint-plugin-storybook` - `storybook-binary`: installs Storybook's `storybook` binary -- `newFrameworks`: removed unused dependencies (eg. `@storybook/builder-webpack5`, `@storybook/manager-webpack5`, `@storybook/builder-vite`) +- `newFrameworks`: removes unused dependencies (eg. `@storybook/builder-webpack5`, `@storybook/manager-webpack5`, `@storybook/builder-vite`) -Click `no` to the following: +Say `no` to the following: -- `autodocsTrue`: we don't need it and it can potentially cause issues with missing dependencies +- `autodocsTrue`: we don't need it and it can potentially cause issues with missing dependencies on your Nx workspace ### 3. Restore the root `.storybook/main.js|ts` file -You will have noticed that the Storybook automigrator added the `framework` option to your root `.storybook/main.js|ts` file. Let's remove that, along with the `autodocs` option. +You will have noticed that the Storybook automigrator added the `framework` option to your root `.storybook/main.js|ts` file. Let's remove that. So, remove: @@ -176,9 +180,11 @@ You can easily find the correct framework by looking at the `builder` option in #### Resulting project-level `.storybook/main.js|ts` file -Here is an example of a project-level `.storybook/main.js|ts` file: +Here is an example of a project-level `.storybook/main.js|ts` file for an Angular project: ```ts +// apps/my-angular-app/.storybook/main.js|ts + const rootMain = require('../../../.storybook/main'); module.exports = { @@ -198,7 +204,7 @@ module.exports = { ### 4. For Vite.js projects -Make sure to add the `viteFinal` option to your project-level `.storybook/main.js|ts` files. +Make sure to add the `viteFinal` option to your project-level `.storybook/main.js|ts` files on projects that use Vite.js. ```ts async viteFinal(config, { configType }) { @@ -214,9 +220,11 @@ Make sure to add the `viteFinal` option to your project-level `.storybook/main.j This will take care of any path resolution issues. -An example of a project-level `.storybook/main.js|ts` file for a Vite.js project: +An example of a project-level `.storybook/main.js|ts` file for a React project that uses Vite.js: ```ts +// apps/my-react-vite-app/.storybook/main.js|ts + const { mergeConfig } = require('vite'); const viteTsConfigPaths = require('vite-tsconfig-paths').default; const rootMain = require('../../../.storybook/main'); @@ -261,4 +269,4 @@ npx nx storybook PROJECT_NAME ## Report any issues and bugs -Since this is a beta version, there are bound to be some issues and bugs. Please report any issues and bugs you find [on the Nx GitHub page](https://github.com/nrwl/nx/issues/new/choose) or on the [Storybook GitHub page](https://github.com/storybookjs/storybook/issues/new/choose). +Since this is a beta version, and the Nx support is still evolving, there are bound to be some issues and bugs. Please report any issues and bugs you find [on the Nx GitHub page](https://github.com/nrwl/nx/issues/new/choose) or on the [Storybook GitHub page](https://github.com/storybookjs/storybook/issues/new/choose). diff --git a/docs/generated/packages/storybook/documents/storybook-7-setup.md b/docs/generated/packages/storybook/documents/storybook-7-setup.md index d90c9466d80b6..6740a8c248d3a 100644 --- a/docs/generated/packages/storybook/documents/storybook-7-setup.md +++ b/docs/generated/packages/storybook/documents/storybook-7-setup.md @@ -1,14 +1,18 @@ # Storybook 7 is here - and Nx is ready +{% callout type="info" title="Available on Nx v15.6" %} +This is a new feature available on Nx v15.6.0. If you are using an older version of Nx, please [upgrade](/packages/nx/documents/migrate). +{% /callout %} + {% callout type="warning" title="Storybook 7 is in beta" %} -[Storybook version 7 is still in beta](https://storybook.js.org/blog/7-0-beta/). Things are evolving dynamically, so it would be better to _avoid using in production_. If you want to use the stable, [6.5 version](https://storybook.js.org/releases/6.5), please go to the [Storybook plugin overview guide](/packages/storybook) to get started. +[Storybook version 7 is still in beta](https://storybook.js.org/blog/7-0-beta/), and so is the Nx support for it. Things are evolving dynamically, so it would be better to _avoid using in production_ on Nx. If you want to use the stable, [6.5 version](https://storybook.js.org/releases/6.5), please go to the [Storybook plugin overview guide](/packages/storybook) to get started. {% /callout %} -Storybook 7 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 7 beta announcement blog post](https://storybook.js.org/blog/7-0-beta/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 7 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). Do note that _version 7 is still in beta_, and things are evolving dynamically, so it would be better to _avoid using in production_. +Storybook 7 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 7 beta announcement blog post](https://storybook.js.org/blog/7-0-beta/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 7 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). Do note that _version 7 is still in beta_, and so is the Nx support for it. Things are evolving dynamically, so it would be better to _avoid using in production_ on Nx. -Nx provides new generators that allow you to generate Storybook 7 configuration for your projects, by installing the correct dependencies, and creating the corresponding version 7 configuration files. +Nx provides new generators that allow you to generate Storybook 7 configuration for your projects, by installing the correct dependencies and creating the corresponding version 7 configuration files. -So, let's see how to get started with Storybook 7 and Nx. +So, let's see how to get started with Storybook 7 on Nx workspaces. ## Setting Up Storybook 7 in a _new_ Nx Workspace diff --git a/docs/map.json b/docs/map.json index 59c9e11d34c42..2d45878a70bd3 100644 --- a/docs/map.json +++ b/docs/map.json @@ -1741,6 +1741,11 @@ "id": "upgrade-storybook-v6-react", "name": "React: Upgrading to Storybook 6", "file": "shared/packages/storybook/storybook-v6-react" + }, + { + "id": "custom-builder-configs", + "name": "Custom configurations for Webpack and Vite", + "file": "shared/packages/storybook/custom-builder-configs" } ] }, diff --git a/docs/shared/packages/storybook/custom-builder-configs.md b/docs/shared/packages/storybook/custom-builder-configs.md new file mode 100644 index 0000000000000..06b582a0bd43d --- /dev/null +++ b/docs/shared/packages/storybook/custom-builder-configs.md @@ -0,0 +1,143 @@ +# Custom configurations for Webpack and Vite + +Storybook allows you to customize the `webpack` configuration and your `vite` configuration. For that, it offers two fields you can add in your `.storybook/main.js|ts` file, called `webpackFinal` and `viteFinal`. These fields are functions that take the default configuration as an argument, and return the modified configuration. You can read more about them in the [Storybook documentation for `webpack`](https://storybook.js.org/docs/react/builders/webpack#extending-storybooks-webpack-config) and the [Storybook documentation for `vite`](https://storybook.js.org/docs/react/builders/vite#configuration). + +You can use these fields in your Nx workspace Storybook configurations normally, following the Storybook docs. However, let's see how you can create a global configuration for every project in your workspace, and how you can override it for specific projects. + +## Global configuration + +In your root `.storybook/main.js|ts` file, you can add the `webpackFinal` or `viteFinal` field, and return the modified configuration. This will be applied to every project in your workspace. + +### `webpack` and `webpackFinal` + +The `webpackFinal` field would look like this: + +```ts +webpackFinal: async (config, { configType }) => { + // Make whatever fine-grained changes you need that should apply to all storybook configs + + // Return the altered config + return config; +}, +``` + +### `vite` and `viteFinal` + +The `viteFinal` field would look like this: + +```ts +async viteFinal(config, { configType }) { + if (configType === 'DEVELOPMENT') { + // Your development configuration goes here + } + if (configType === 'PRODUCTION') { + // Your production configuration goes here. + } + return mergeConfig(config, { + // Your environment configuration here + }); + }, +``` + +In the `viteFinal` case, you would have to import the `mergeConfig` function from `vite`. So, on the top of your root `.storybook/main.js|ts` file, you would have to add: + +```ts +const { mergeConfig } = require('vite'); +``` + +## Project-specific configuration + +### `webpack` and `webpackFinal` + +You can customize or extend the global `webpack` configuration for a specific project by adding a `webpackFinal` field in your project-specific `.storybok/main.js|ts` file, like this: + +```ts +// apps/my-react-webpack-app/.storybook/main.js + +const rootMain = require('../../../.storybook/main'); + +module.exports = { + ...rootMain, + ... + webpackFinal: async (config, { configType }) => { + // apply any global webpack configs that might have been specified in .storybook/main.js + if (rootMain.webpackFinal) { + config = await rootMain.webpackFinal(config, { configType }); + } + + // add your own webpack tweaks if needed + + return config; + }, +}; +``` + +Take note how we are first applying the global `webpack` configuration, and then adding our own tweaks. If you don't want to apply any global configuration, you can just return your own configuration, and skip the `rootMain.webpackFinal` check. + +### `vite` and `viteFinal` + +You can customize or extend the global `vite` configuration for a specific project by adding a `viteFinal` field in your project-specific `.storybok/main.js|ts` file. + +{% callout type="check" title="Don't forget the vite-tsconfig-paths plugin" %} +For Vite.js to work on monorepos, and specifically on Nx workspaces, you need to use the `'vite-tsconfig-paths'` plugin! +{% /callout %} + +It's important to note here that for Vite.js to work on monorepos, and specifically on Nx workspaces, you need to use the `'vite-tsconfig-paths'` plugin, just like you must already do in your project's `vite.config.ts` file. Storybook does not read your project's Vite configuration automatically, so you have to manually add the plugin to your project's Storybook Vite configuration. + +So, a project-level `.storybook/main.js|ts` file for a Vite.js project would look like this: + +```ts +// apps/my-react-vite-app/.storybook/main.js +const { mergeConfig } = require('vite'); +const viteTsConfigPaths = require('vite-tsconfig-paths').default; +const rootMain = require('../../../.storybook/main'); + +module.exports = { + ...rootMain, + core: { ...rootMain.core, builder: '@storybook/builder-vite' }, + stories: [ + ...rootMain.stories, + '../src/app/**/*.stories.mdx', + '../src/app/**/*.stories.@(js|jsx|ts|tsx)', + ], + addons: [...rootMain.addons], + async viteFinal(config, { configType }) { + return mergeConfig(config, { + ...((await rootMain.viteFinal(config, { configType })) ?? {}), + plugins: [ + viteTsConfigPaths({ + root: '../../../', + }), + ], + }); + }, +}; +``` + +or just simplified (if you don't want to take into account any global Storybook Vite.js configuration): + +```ts +const { mergeConfig } = require('vite'); +const viteTsConfigPaths = require('vite-tsconfig-paths').default; +const rootMain = require('../../../.storybook/main'); + +module.exports = { + ...rootMain, + core: { ...rootMain.core, builder: '@storybook/builder-vite' }, + stories: [ + ...rootMain.stories, + '../src/app/**/*.stories.mdx', + '../src/app/**/*.stories.@(js|jsx|ts|tsx)', + ], + addons: [...rootMain.addons], + async viteFinal(config, { configType }) { + return mergeConfig(config, { + plugins: [ + viteTsConfigPaths({ + root: '../../../', + }), + ], + }); + }, +}; +``` diff --git a/docs/shared/packages/storybook/migrate-storybook-7.md b/docs/shared/packages/storybook/migrate-storybook-7.md index e63fc33afef17..1d74ffe95aee6 100644 --- a/docs/shared/packages/storybook/migrate-storybook-7.md +++ b/docs/shared/packages/storybook/migrate-storybook-7.md @@ -1,25 +1,29 @@ -# Migrate to Storybook to version 7 +# Migrate your Nx workspace to Storybook version 7 + +{% callout type="info" title="Available on Nx v15.5" %} +This is a new feature available on Nx v15.5.0. If you are using an older version of Nx, please [upgrade](/packages/nx/documents/migrate). +{% /callout %} {% callout type="warning" title="Storybook 7 is in beta" %} -[Storybook version 7 is still in beta](https://storybook.js.org/blog/7-0-beta/). Things are evolving dynamically, so it would be better to _avoid using in production_. If you want to use the stable, [6.5 version](https://storybook.js.org/releases/6.5), please go to the [Storybook plugin overview guide](/packages/storybook) to get started. +[Storybook version 7 is still in beta](https://storybook.js.org/blog/7-0-beta/), and so is the Nx support for it. Things are evolving dynamically, so it would be better to _avoid using in production_ on Nx. If you want to use the stable, [6.5 version](https://storybook.js.org/releases/6.5), please go to the [Storybook plugin overview guide](/packages/storybook) to get started. {% /callout %} {% callout type="info" title="Setting up Storybook 7 in a new workspace" %} -For settin up Storybook version 7 in a new Nx workspace, or a workspace that does NOT already have Storybook configured already, please refer to our [Storybook 7 setup guide](/packages/storybook/documents/storybook-7-setup). +For setting up Storybook version 7 in a new Nx workspace, or a workspace that does NOT already have Storybook configured already, please refer to our [Storybook 7 setup guide](/packages/storybook/documents/storybook-7-setup). {% /callout %} -Storybook 7 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 7 beta announcement blog post](https://storybook.js.org/blog/7-0-beta/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 7 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). Do note that _version 7 is still in beta_, and things are evolving dynamically, so it would be better to _avoid using in production_. +Storybook 7 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 7 beta announcement blog post](https://storybook.js.org/blog/7-0-beta/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 7 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). Do note that _version 7 is still in beta_, and so is the Nx support for it. Things are evolving dynamically, so it would be better to _avoid using in production_ on Nx. You can now migrate your existing Nx workspace with Storybook configuration to use Storybook version 7. This guide will show you how to do that. ## Use the Storybook CLI to upgrade -You can take advantage of the Storybook CLI to automatically migrate some settings of your Storybook setup. For a full guide to migration using the Storybook CLI, please refer to the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). +You can take advantage of the Storybook CLI to automatically migrate some settings of your Storybook setup on your Nx workspace. For a full guide to migration using the Storybook CLI, please refer to the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). -The Storybook migration scripts do not work perfectly with Nx, however we can use them to get the latest beta versions of our packages, remove some unused packages, and get a hint of some settings that we will need to change manually, eventually. +The Storybook migration scripts do not work perfectly on Nx workspaces, however we can use them to get the latest beta versions of our packages, remove some unused packages and get a hint of some settings that we will need to change manually, eventually. {% callout type="warning" title="Don't use in production" %} -Please take extra care when migrating your existing Storybook setup to version 7. Do not use in production, since it's still in beta. +Please take extra care when migrating your existing Storybook setup to version 7 on your Nx workspace. Do not use in production, since it's still in beta, and the Nx support is not stable yet. {% /callout %} Let's see the steps we can make to migrate our Storybook setup to version 7. @@ -37,24 +41,24 @@ This will: For more info, see [here](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). -### 2. Click yes to the automigration prompts +### 2. Say `yes` to the automigration prompts The Storybook CLI will prompt you to run some code generators and modifiers. -Click `yes` to the following: +Say `yes` to the following: - `mainjsFramework`: It will add the `framework` field in your root `.storybook/main.js|ts` file. We are going to delete it since it's not needed in the root file, but it's handy to have it ready to copy. Also, it shows you an indication of what it looks like. - `eslintPlugin`: installs the `eslint-plugin-storybook` - `storybook-binary`: installs Storybook's `storybook` binary -- `newFrameworks`: removed unused dependencies (eg. `@storybook/builder-webpack5`, `@storybook/manager-webpack5`, `@storybook/builder-vite`) +- `newFrameworks`: removes unused dependencies (eg. `@storybook/builder-webpack5`, `@storybook/manager-webpack5`, `@storybook/builder-vite`) -Click `no` to the following: +Say `no` to the following: -- `autodocsTrue`: we don't need it and it can potentially cause issues with missing dependencies +- `autodocsTrue`: we don't need it and it can potentially cause issues with missing dependencies on your Nx workspace ### 3. Restore the root `.storybook/main.js|ts` file -You will have noticed that the Storybook automigrator added the `framework` option to your root `.storybook/main.js|ts` file. Let's remove that, along with the `autodocs` option. +You will have noticed that the Storybook automigrator added the `framework` option to your root `.storybook/main.js|ts` file. Let's remove that. So, remove: @@ -176,9 +180,11 @@ You can easily find the correct framework by looking at the `builder` option in #### Resulting project-level `.storybook/main.js|ts` file -Here is an example of a project-level `.storybook/main.js|ts` file: +Here is an example of a project-level `.storybook/main.js|ts` file for an Angular project: ```ts +// apps/my-angular-app/.storybook/main.js|ts + const rootMain = require('../../../.storybook/main'); module.exports = { @@ -198,7 +204,7 @@ module.exports = { ### 4. For Vite.js projects -Make sure to add the `viteFinal` option to your project-level `.storybook/main.js|ts` files. +Make sure to add the `viteFinal` option to your project-level `.storybook/main.js|ts` files on projects that use Vite.js. ```ts async viteFinal(config, { configType }) { @@ -214,9 +220,11 @@ Make sure to add the `viteFinal` option to your project-level `.storybook/main.j This will take care of any path resolution issues. -An example of a project-level `.storybook/main.js|ts` file for a Vite.js project: +An example of a project-level `.storybook/main.js|ts` file for a React project that uses Vite.js: ```ts +// apps/my-react-vite-app/.storybook/main.js|ts + const { mergeConfig } = require('vite'); const viteTsConfigPaths = require('vite-tsconfig-paths').default; const rootMain = require('../../../.storybook/main'); @@ -261,4 +269,4 @@ npx nx storybook PROJECT_NAME ## Report any issues and bugs -Since this is a beta version, there are bound to be some issues and bugs. Please report any issues and bugs you find [on the Nx GitHub page](https://github.com/nrwl/nx/issues/new/choose) or on the [Storybook GitHub page](https://github.com/storybookjs/storybook/issues/new/choose). +Since this is a beta version, and the Nx support is still evolving, there are bound to be some issues and bugs. Please report any issues and bugs you find [on the Nx GitHub page](https://github.com/nrwl/nx/issues/new/choose) or on the [Storybook GitHub page](https://github.com/storybookjs/storybook/issues/new/choose). diff --git a/docs/shared/packages/storybook/storybook-7-setup.md b/docs/shared/packages/storybook/storybook-7-setup.md index d90c9466d80b6..6740a8c248d3a 100644 --- a/docs/shared/packages/storybook/storybook-7-setup.md +++ b/docs/shared/packages/storybook/storybook-7-setup.md @@ -1,14 +1,18 @@ # Storybook 7 is here - and Nx is ready +{% callout type="info" title="Available on Nx v15.6" %} +This is a new feature available on Nx v15.6.0. If you are using an older version of Nx, please [upgrade](/packages/nx/documents/migrate). +{% /callout %} + {% callout type="warning" title="Storybook 7 is in beta" %} -[Storybook version 7 is still in beta](https://storybook.js.org/blog/7-0-beta/). Things are evolving dynamically, so it would be better to _avoid using in production_. If you want to use the stable, [6.5 version](https://storybook.js.org/releases/6.5), please go to the [Storybook plugin overview guide](/packages/storybook) to get started. +[Storybook version 7 is still in beta](https://storybook.js.org/blog/7-0-beta/), and so is the Nx support for it. Things are evolving dynamically, so it would be better to _avoid using in production_ on Nx. If you want to use the stable, [6.5 version](https://storybook.js.org/releases/6.5), please go to the [Storybook plugin overview guide](/packages/storybook) to get started. {% /callout %} -Storybook 7 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 7 beta announcement blog post](https://storybook.js.org/blog/7-0-beta/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 7 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). Do note that _version 7 is still in beta_, and things are evolving dynamically, so it would be better to _avoid using in production_. +Storybook 7 is a major release that brings a lot of new features and improvements. You can read more about it in the [Storybook 7 beta announcement blog post](https://storybook.js.org/blog/7-0-beta/). Apart from the new features and improvements it introduces, it also brings some breaking changes. You can read more about them in the [Storybook 7 migration docs](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and the [Storybook 7 migration guide](https://chromatic-ui.notion.site/Storybook-7-migration-guide-dbf41fa347304eb2a5e9c69b34503937). Do note that _version 7 is still in beta_, and so is the Nx support for it. Things are evolving dynamically, so it would be better to _avoid using in production_ on Nx. -Nx provides new generators that allow you to generate Storybook 7 configuration for your projects, by installing the correct dependencies, and creating the corresponding version 7 configuration files. +Nx provides new generators that allow you to generate Storybook 7 configuration for your projects, by installing the correct dependencies and creating the corresponding version 7 configuration files. -So, let's see how to get started with Storybook 7 and Nx. +So, let's see how to get started with Storybook 7 on Nx workspaces. ## Setting Up Storybook 7 in a _new_ Nx Workspace