From 22cd42f8c5548e7d16045b631e472f9e344907a2 Mon Sep 17 00:00:00 2001 From: Kyle Gach Date: Mon, 10 Jun 2024 11:09:20 -0600 Subject: [PATCH] Merge pull request #28136 from storybookjs/shilman/package-structure-changes Documentation: Package structure changes across major versions (cherry picked from commit a496ec48c708eed753a5251d55fa07947a869e62) --- MIGRATION.md | 47 ++++++++++++++-------- docs/migration-guide/from-older-version.md | 27 +++++++++++-- docs/migration-guide/index.md | 27 +++++++++++-- 3 files changed, 79 insertions(+), 22 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 22bd0a923f32..4fab1b7e3c50 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -17,6 +17,7 @@ - [Manager addons are now rendered with React 18](#manager-addons-are-now-rendered-with-react-18) - [Removal of `storiesOf`-API](#removal-of-storiesof-api) - [Removed deprecated shim packages](#removed-deprecated-shim-packages) + - [Deprecated `@storybook/testing-library` package](#deprecated-storybooktesting-library-package) - [Framework-specific Vite plugins have to be explicitly added](#framework-specific-vite-plugins-have-to-be-explicitly-added) - [For React:](#for-react) - [For Vue:](#for-vue) @@ -97,17 +98,17 @@ - [Tab addons cannot manually route, Tool addons can filter their visibility via tabId](#tab-addons-cannot-manually-route-tool-addons-can-filter-their-visibility-via-tabid) - [Removed `config` preset](#removed-config-preset-1) - [From version 7.5.0 to 7.6.0](#from-version-750-to-760) - - [CommonJS with Vite is deprecated](#commonjs-with-vite-is-deprecated) - - [Using implicit actions during rendering is deprecated](#using-implicit-actions-during-rendering-is-deprecated) - - [typescript.skipBabel deprecated](#typescriptskipbabel-deprecated) - - [Primary doc block accepts of prop](#primary-doc-block-accepts-of-prop) - - [Addons no longer need a peer dependency on React](#addons-no-longer-need-a-peer-dependency-on-react) + - [CommonJS with Vite is deprecated](#commonjs-with-vite-is-deprecated) + - [Using implicit actions during rendering is deprecated](#using-implicit-actions-during-rendering-is-deprecated) + - [typescript.skipBabel deprecated](#typescriptskipbabel-deprecated) + - [Primary doc block accepts of prop](#primary-doc-block-accepts-of-prop) + - [Addons no longer need a peer dependency on React](#addons-no-longer-need-a-peer-dependency-on-react) - [From version 7.4.0 to 7.5.0](#from-version-740-to-750) - - [`storyStoreV6` and `storiesOf` is deprecated](#storystorev6-and-storiesof-is-deprecated) - - [`storyIndexers` is replaced with `experimental_indexers`](#storyindexers-is-replaced-with-experimental_indexers) + - [`storyStoreV6` and `storiesOf` is deprecated](#storystorev6-and-storiesof-is-deprecated) + - [`storyIndexers` is replaced with `experimental_indexers`](#storyindexers-is-replaced-with-experimental_indexers) - [From version 7.0.0 to 7.2.0](#from-version-700-to-720) - - [Addon API is more type-strict](#addon-api-is-more-type-strict) - - [Addon-controls hideNoControlsWarning parameter is deprecated](#addon-controls-hidenocontrolswarning-parameter-is-deprecated) + - [Addon API is more type-strict](#addon-api-is-more-type-strict) + - [Addon-controls hideNoControlsWarning parameter is deprecated](#addon-controls-hidenocontrolswarning-parameter-is-deprecated) - [From version 6.5.x to 7.0.0](#from-version-65x-to-700) - [7.0 breaking changes](#70-breaking-changes) - [Dropped support for Node 15 and below](#dropped-support-for-node-15-and-below) @@ -133,7 +134,7 @@ - [Deploying build artifacts](#deploying-build-artifacts) - [Dropped support for file URLs](#dropped-support-for-file-urls) - [Serving with nginx](#serving-with-nginx) - - [Ignore story files from node\_modules](#ignore-story-files-from-node_modules) + - [Ignore story files from node_modules](#ignore-story-files-from-node_modules) - [7.0 Core changes](#70-core-changes) - [7.0 feature flags removed](#70-feature-flags-removed) - [Story context is prepared before for supporting fine grained updates](#story-context-is-prepared-before-for-supporting-fine-grained-updates) @@ -147,7 +148,7 @@ - [Addon-interactions: Interactions debugger is now default](#addon-interactions-interactions-debugger-is-now-default) - [7.0 Vite changes](#70-vite-changes) - [Vite builder uses Vite config automatically](#vite-builder-uses-vite-config-automatically) - - [Vite cache moved to node\_modules/.cache/.vite-storybook](#vite-cache-moved-to-node_modulescachevite-storybook) + - [Vite cache moved to node_modules/.cache/.vite-storybook](#vite-cache-moved-to-node_modulescachevite-storybook) - [7.0 Webpack changes](#70-webpack-changes) - [Webpack4 support discontinued](#webpack4-support-discontinued) - [Babel mode v7 exclusively](#babel-mode-v7-exclusively) @@ -197,7 +198,7 @@ - [Dropped addon-docs manual babel configuration](#dropped-addon-docs-manual-babel-configuration) - [Dropped addon-docs manual configuration](#dropped-addon-docs-manual-configuration) - [Autoplay in docs](#autoplay-in-docs) - - [Removed STORYBOOK\_REACT\_CLASSES global](#removed-storybook_react_classes-global) + - [Removed STORYBOOK_REACT_CLASSES global](#removed-storybook_react_classes-global) - [7.0 Deprecations and default changes](#70-deprecations-and-default-changes) - [storyStoreV7 enabled by default](#storystorev7-enabled-by-default) - [`Story` type deprecated](#story-type-deprecated) @@ -439,6 +440,7 @@ The `docs.autodocs` setting in `main.js` is deprecated in 8.1 and will be remove It has been replaced with a tags-based system which is more flexible than before. `docs.autodocs` takes three values: + - `true`: generate autodocs for every component - `false`: don't generate autodocs at all - `tag`: generate autodocs for components that have been tagged `'autodocs'`. @@ -448,8 +450,8 @@ Starting in 8.1, to generate autodocs for every component (`docs.autodocs = true ```js // .storybook/preview.js export default { - tags: ['autodocs'], -} + tags: ["autodocs"], +}; ``` Tags cascade, so setting `'autodocs'` at the project level automatically propagates to every component and story. If you set autodocs globally and want to opt-out for a particular component, you can remove the `'autodocs'` tag for a component like this: @@ -458,8 +460,8 @@ Tags cascade, so setting `'autodocs'` at the project level automatically propaga // Button.stories.ts export default { component: Button, - tags: ['!autodocs'], -} + tags: ["!autodocs"], +}; ``` If you had set `docs.autodocs = 'tag'`, the default setting, you can remove the setting from `.storybook/main.js`. That is now the default behavior. @@ -602,6 +604,19 @@ These sections explain the rationale, and the required changes you might have to - [New Addons API](#new-addons-api) - [`addons.setConfig` should now be imported from `@storybook/manager-api`.](#addonssetconfig-should-now-be-imported-from-storybookmanager-api) +### Deprecated `@storybook/testing-library` package + +In Storybook 8, `@storybook/testing-library` has been integrated to a new package called `@storybook/test`, which uses Vitest APIs for an improved experience. When upgrading to Storybook 8 with 'npx storybook@latest upgrade', you will get prompted and will get an automigration for the new package. Please migrate when you can. + +To migrate by hand, install `@storybook/test` and replace `@storybook/testing-libary` imports globally: + +```ts +- import { userEvent } from '@storybook/testing-library'; ++ import { userEvent } from '@storybook/test'; +``` + +For more information on the change, see the [announcement post](https://storybook.js.org/blog/storybook-test/). + ### Framework-specific Vite plugins have to be explicitly added In Storybook 7, we would automatically add frameworks-specific Vite plugins, e.g. `@vitejs/plugin-react` if not installed. diff --git a/docs/migration-guide/from-older-version.md b/docs/migration-guide/from-older-version.md index c368c48e39be..db31dec1ceb5 100644 --- a/docs/migration-guide/from-older-version.md +++ b/docs/migration-guide/from-older-version.md @@ -7,9 +7,8 @@ Storybook 8 focuses on improving performance, compatibility, and stability. Key - 🩻 A new visual testing workflow via [the Visual Tests addon](https://www.chromatic.com/docs/visual-tests-addon/) - 💨 [2-4x faster test builds](https://storybook.js.org/blog/optimize-storybook-7-6/#2-4x-faster-builds-with-thetest-flag), [25-50% faster React docgen](https://storybook.js.org/blog/optimize-storybook-7-6/#22x-faster-react-docgen), and [SWC support for Webpack projects](https://storybook.js.org/blog/optimize-storybook-7-6/#using-webpack-enable-swc) - 🧩 Improved framework support: you no longer need to install React as a peer dependency when using a non-React renderer -- 🎛️ Strengthened control generation in [React](https://storybook.js.org/blog/storybook-8-beta/#major-performance-improvements -) and [Vue](https://storybook.js.org/blog/first-class-vue-support-storybook-8/) projects -- ⚡️ Improved Vite architecture, Vitest testing, and Vite 5 support +- 🎛️ Strengthened control generation in [React](https://storybook.js.org/blog/storybook-8-beta/#major-performance-improvements) and [Vue](https://storybook.js.org/blog/first-class-vue-support-storybook-8/) projects +- ⚡️ Improved Vite architecture, Vitest testing, and Vite 5 support - 🌐 [Support for React Server Components (RSC)](https://storybook.js.org/blog/storybook-react-server-components/): our experimental solution renders async RSC in the browser and mocks Node code - ✨ A refreshed desktop UI & mobile UX - ➕ Much, much more @@ -24,6 +23,7 @@ The rest of this guide will help you upgrade successfully, either automatically - [Start and build CLI binaries removed](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#start-storybook--build-storybook-binaries-removed) - [`storiesOf` API has been removed](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#removal-of-storiesof-api) - [`*.stories.mdx` format has been removed](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropping-support-for-storiesmdx-csf-in-mdx-format-and-mdx1-support) +- [Packages have been consolidated/removed](#package-structure-changes) - [Implicit actions (from `argTypesRegex`) can no longer be used during rendering (e.g. in a play function)](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#implicit-actions-can-not-be-used-during-rendering-for-example-in-the-play-function) - [`react-docgen` (instead of `react-docgen-typescript`) is the default for component analysis](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#react-docgen-component-analysis-by-default) - [Storyshots has been removed](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#storyshots-has-been-removed) @@ -88,6 +88,27 @@ Storybook 8 uses MDX 3. If you're coming from MDX 1 (used by Storybook 6), there If you are using Vite, you may now need to create a `vite.config.js` file in your project root to allow newer versions of Vite to work with Storybook. Additionally, you may need to install and configure a Vite plugin for your framework. More information is available in the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#framework-specific-vite-plugins-have-to-be-explicitly-added). +## Package structure changes + +The following packages are **removed**. See the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#removed-deprecated-shim-packages) for details. + +| Removal | Replacement | +| -------------------------------- | ----------------------------------------------------- | +| `@storybook/addons` | `@storybook/manager-api` or `@storyboook/preview-api` | +| `@storybook/channel-postmessage` | `@storybook/channels` | +| `@storybook/channel-websocket` | `@storybook/channels` | +| `@storybook/client-api` | `@storybook/preview-api` | +| `@storybook/core-client` | `@storybook/preview-api` | +| `@storybook/preview-web` | `@storybook/preview-api` | +| `@storybook/store` | `@storybook/preview-api` | +| `@storybook/api` | `@storybook/manager-api` | + +The following packages are **deprecated**. See the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-storybooktesting-library-package) for details. + +| Deprecation | Replacement | +| ---------------------------- | ----------------- | +| `@storybook/testing-library` | `@storybook/test` | + ## Troubleshooting The automatic upgrade should get your Storybook into a working state. If you encounter an error running Storybook after upgrading, here’s what to do: diff --git a/docs/migration-guide/index.md b/docs/migration-guide/index.md index 51962ca7b88d..3de5a23a9c63 100644 --- a/docs/migration-guide/index.md +++ b/docs/migration-guide/index.md @@ -7,9 +7,8 @@ Storybook 8 focuses on improving performance, compatibility, and stability. Key - 🩻 A new visual testing workflow via [the Visual Tests addon](https://www.chromatic.com/docs/visual-tests-addon/) - 💨 [2-4x faster test builds](https://storybook.js.org/blog/optimize-storybook-7-6/#2-4x-faster-builds-with-thetest-flag), [25-50% faster React docgen](https://storybook.js.org/blog/optimize-storybook-7-6/#22x-faster-react-docgen), and [SWC support for Webpack projects](https://storybook.js.org/blog/optimize-storybook-7-6/#using-webpack-enable-swc) - 🧩 Improved framework support: you no longer need to install React as a peer dependency when using a non-React renderer -- 🎛️ Strengthened control generation in [React](https://storybook.js.org/blog/storybook-8-beta/#major-performance-improvements -) and [Vue](https://storybook.js.org/blog/first-class-vue-support-storybook-8/) projects -- ⚡️ Improved Vite architecture, Vitest testing, and Vite 5 support +- 🎛️ Strengthened control generation in [React](https://storybook.js.org/blog/storybook-8-beta/#major-performance-improvements) and [Vue](https://storybook.js.org/blog/first-class-vue-support-storybook-8/) projects +- ⚡️ Improved Vite architecture, Vitest testing, and Vite 5 support - 🌐 [Support for React Server Components (RSC)](https://storybook.js.org/blog/storybook-react-server-components/): our experimental solution renders async RSC in the browser and mocks Node code - ✨ A refreshed desktop UI & mobile UX - ➕ Much, much more @@ -30,6 +29,7 @@ The rest of this guide will help you upgrade successfully, either automatically - [`storiesOf` API has been removed](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#removal-of-storiesof-api) - [`*.stories.mdx` format has been removed](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropping-support-for-storiesmdx-csf-in-mdx-format-and-mdx1-support) +- [Packages have been consolidated/removed](#package-structure-changes) - [Implicit actions (from `argTypesRegex`) can no longer be used during rendering (e.g. in a play function)](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#implicit-actions-can-not-be-used-during-rendering-for-example-in-the-play-function) - [`react-docgen` (instead of `react-docgen-typescript`) is the default for component analysis](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#react-docgen-component-analysis-by-default) - [Storyshots has been removed](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#storyshots-has-been-removed) @@ -152,6 +152,27 @@ If you prefer to debug yourself, here are a few useful things you can do to help 1. Try removing all addons that are not in the `@storybook` npm namespace (make sure you don't remove the `storybook` package). Community addons that work well with 7.x might not yet be compatible with 8.0, and this is the fastest way to isolate that possibility. If you find an addon that needs to be upgraded to work with Storybook 8, please post an issue on the addon’s repository, or better yet, a pull request to upgrade it! 2. Another debugging technique is to bisect to older prerelease versions of Storybook to figure out which release broke your Storybook. For example, assuming that the current prerelease of Storybook is `8.0.0-beta.56`, you could set the version to `8.0.0-alpha.0` in your `package.json` and reinstall to verify that it still works (`alpha.0` should be nearly identical to `7.6.x`). If it works, you could then try `8.0.0-beta.0`, then `8.0.0-beta.28` and so forth. Once you’ve isolated the bad release, read through its [CHANGELOG](https://github.com/storybookjs/storybook/blob/next/CHANGELOG.md) entry and perhaps there’s a change that jumps out as the culprit. If you find the problem, please submit an issue or pull request to the Storybook monorepo and we’ll do our best to take care of it quickly. +## Package structure changes + +The following packages are **removed**. See the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#removed-deprecated-shim-packages) for details. + +| Removal | Replacement | +| -------------------------------- | ----------------------------------------------------- | +| `@storybook/addons` | `@storybook/manager-api` or `@storyboook/preview-api` | +| `@storybook/channel-postmessage` | `@storybook/channels` | +| `@storybook/channel-websocket` | `@storybook/channels` | +| `@storybook/client-api` | `@storybook/preview-api` | +| `@storybook/core-client` | `@storybook/preview-api` | +| `@storybook/preview-web` | `@storybook/preview-api` | +| `@storybook/store` | `@storybook/preview-api` | +| `@storybook/api` | `@storybook/manager-api` | + +The following packages are **deprecated**. See the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-storybooktesting-library-package) for details. + +| Deprecation | Replacement | +| ---------------------------- | ----------------- | +| `@storybook/testing-library` | `@storybook/test` | + ## Optional migrations In addition to the automigrations and manual migrations above, there are also optional migrations that you should consider. These are features that we’ve deprecated in Storybook 8 (but remain backwards compatible), or best practices that should help you be more productive in the future.