Merge pull request #25618 from storybookjs/vy/addon-migration-guide-8

Author: vanessayuenn

docs/addons/addon-migration-guide.md

@@ -1,77 +1,66 @@
 ---
-title: Addon migration guide for Storybook 7.0
+title: Addon migration guide for Storybook 8.0
 ---
 
-Storybook 7 is our first major release in over two years. While Storybook’s addon API has not changed much in the past couple of years, addons require several changes for compatibility with Storybook 7. This guide will walk you through the upgrade process.
+We deeply appreciate the dedication and effort addon creators put into keeping the Storybook ecosystem vibrant and up-to-date. As Storybook evolves to version 8.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 7.x to 8.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the [Addon migration guide for Storybook 7.0](https://storybook.js.org/docs/7.6/addons/addon-migration-guide).
 
 <Callout variant="info">
 
 As we gather feedback from the community, we’ll update this page. We also have a general [Storybook migration guide](../migration-guide.md) if you’re looking for that.
 
 </Callout>
 
-## Dependencies
+## Updating dependencies
 
-The first thing to do is upgrade any Storybook dependencies in your project. We release the next version of all our packages on the `next` npm tag, so the easiest thing is to reference that in your `package.json`:
+Begin by updating your Storybook dependencies. Use the `next` tag for pre-release versions, `latest` for the most recent stable release, or specify the version directly.
 
 ```json
 {
   "dependencies": {
-    "@storybook/client-logger": "next"
+    "@storybook/client-logger": "next" // or "latest", or "^8.0.0"
   }
 }
 ```
 
-If you'd rather depend on the latest version of Storybook, you can use the `latest` tag:
+## Key changes for addons
 
-```json
-{
-  "dependencies": {
-    "@storybook/client-logger": "latest"
-  }
-}
-```
+Here are the essential changes in version 8.0 that impact addon development. Please check the [full migration note](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-7x-to-800) for an exhaustive list of changes in 8.0.
 
-Or use a version specifier:
+### Node.js 16 support dropped
 
-```json
-{
-  "dependencies": {
-    "@storybook/client-logger": "^7.0.0"
-  }
-}
-```
+Please upgrade your addon to Node.js 18, as support for Node.js 16 has ended.
 
-## Breaking changes
+### React 18 for manager UI
 
-### `@storybook/addons` has been split into `@storybook/manager-api` and `@storybook/preview-api`
+UI injected into panels, tools, etc. by addons is now rendered with React 18. Also note that the `key` prop is no longer passed to the render function.
 
-The default export from `@storybook/addons` can now be used via named imports from `@storybook/manager-api` and `@storybook/preview-api`, depending on which environment you need the API from. The manager is the Storybook UI and includes your addon's Addon Panel. While the preview is used to render stories and includes your addon's decorators.
+### @storybook/components deprecations
 
-You might also depend (and use) these packages in your addon's decorators: `@storybook/store`, `@storybook/preview-web`, `@storybook/core-client`, `@storybook/client-api`. These have all been consolidated into `@storybook/preview-api`. If you use any of these packages, please import what you need from `@storybook/preview-api` instead.
+`Icons` component from `@storybook/components` is now deprecated in favor of [`@storybook/icons`](https://github.com/storybookjs/icons). Additionally, various `Button` component props are also deprecated, with alternatives provided.
 
-### Some components were moved from `@storybook/components` to a new package `@storybook/blocks`
+### Storybook layout state API changes
 
-Components like `ColorControl`, `ColorPalette`, `ArgsTable`, `ArgRow`, `TabbedArgsTable`, `SectionRow`, `Source`, AND `Code` were moved into a new package. In Storybook 7.0, they should be imported from `@storybook/blocks` instead.
+If you're customizing the Storybook UI configuration with `addons.setConfig({...})`, be aware of [the changes to the layout state API](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#ui-layout-state-has-changed-shape).
 
-```js
-// import { ColorControl } from '@storybook/components';
-import { ColorControl } from '@storybook/blocks';
-```
+### Removal of deprecated features
 
-## Deprecations and detailed migrations
+Deprecated packages and APIs from 7.0 are now removed in 8.0.Consult the [full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecations-which-are-now-removed) for details. Most notably for addons, the removal of the `@storybook/addons` now necessitates a switch to `@storybook/preview-api` and `@storybook/manager-api`.
 
-We’ve also deprecated a few packages and APIs in 7.0. After you’ve made your addon working with 7.0, make sure to check the browser console in a Storybook running your addon. If you’re using deprecated packages, you should see warnings that link to migration instructions.
+### Babel-loader removed from webpack
 
-There are more technical details available in the [migration notes for addon authors](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#specific-instructions-for-addon-creators).
+Storybook 8 [removes babel-loader from the webpack5 builder](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#removed-babelcore-and-babel-loader-from-storybookbuilder-webpack5). If your addon's preset overrides the `babel()` method, it will break if your users are using SWC to compile their files (which is the new default for Webpack 5-based Storybook projects).
 
-Finally, for an exhaustive list of noteworthy changes in 7.0, check [the full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700).
+To solve for both Babel and SWC, the most robust approach is to create an [unplugin](https://github.com/unjs/unplugin) that will work with both Webpack and Vite builders. That will give you full control to run Babel (or whatever you want) on stories and components as they are loaded.
 
-## Releasing
+As a workaround, update your documentation to tell users to opt-in to Babel support. This should fix your addon in their project, at the cost of performance:
+
+```sh
+npx storybook@latest add @storybook/addon-webpack5-compiler-babel
+```
 
-You should release a new major version of this addon that supports Storybook 7. If you want to continue making changes that support Storybook 6, you should release a minor or a patch of the previous major version.
+## Releasing
 
-We also recommend releasing your own addon using the `next` tag to test it out in projects.
+Release a new major version of your addon for Storybook 8.0. We recommend you to continue supporting 7.x with minor or patch versions. We also recommend releasing your own addon using the `next` tag to test it out in projects.
 
 ## Support