GitHub/storybook
1
0
Fork 0
mirror of https://github.com/storybookjs/storybook.git synced 2025-04-09 00:19:13 +08:00
Code Issues Packages Projects Releases Wiki Activity
storybook/docs/migration-guide/from-older-version.mdx
Shota FUJI 7a32c16cfd
Docs: Fix broken links ending with ".mdx" 
When I checked "How to contribute" page on storybook.js.org, a link
titled "Continue reading our contributor covenant" pointed to GitHub's
404 page. The last item of the URL path was "CODE_OF_CONDUCT.mdx", which
is not common filename people uses, therefore I suspected this is not
the only broken link in the docs.

And I was right. I ran the below command (rg = RipGrep) then found
several 404 links.

```
$ cd docs
$ rg "https?:[\S)]+mdx\)" --sort path
```

Git blame told me that some of ".md" to ".mdx" migration works
accidentally changed non-docs URLs ending with ".md" too.

StackBlitz URL in docs/api/main-config/main-config-indexers.mdx is not
actually a dead link, as the service redirects to the `README.md`.
However, the redirection takes loooong so I replaced that as well.

There are still two links that match to the above regexp:

* <https://github.com/storybookjs/storybook/blob/next/docs/get-started/setup.mdx>
  at docs/contribute/documentation/new-snippets.mdx L42
* <https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx>
  at docs/writing-docs/mdx.mdx

but those two are both valid (alive) URLs.
2024-09-05 15:30:37 +09:00

137 lines
12 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
title: 'Migration guide from Storybook 6.x to 8.0'
sidebar:
order: 1
title: Migrate from 6.x to 8.0
---
Storybook 8 focuses on improving performance, compatibility, and stability. Key features include:
* 🩻 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
* 🌐 [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
This guide is meant to help you **upgrade from Storybook 6.x to 8.0** successfully!
## Major breaking changes
The rest of this guide will help you upgrade successfully, either automatically or manually. But first, we’ve accumulated a lot of breaking changes in both [Storybook 7](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#70-breaking-changes) and [Storybook 8](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-7x-to-800). Here are the most impactful changes you should know about before you go further:
* [`framework` field is now mandatory](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#new-framework-api)
* [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)
* [Addons API introduced in Storybook 7 is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#new-addons-api)
* Ecosystem updates
* [Webpack4 support discontinued](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#webpack4-support-discontinued)
* [IE11 support discontinued](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#modern-browser-support)
* [Node 18+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropping-support-for-nodejs-16)
* [Next.js 13.5+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#require-nextjs-135-and-up)
* [Vue 3+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#require-vue-3-and-up)
* [Angular 15+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#require-angular-15-and-up)
* [Svelte 4+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#require-svelte-4-and-up)
* [Yarn 1 is no longer supported](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#dropping-support-for-yarn-1)
If any of these changes apply to your project, please read through the linked migration notes before continuing.
If any of these new requirements or changes are blockers for your project, we recommend looking at the [requirements to migrate to Storybook 7](../../release-7-6/docs/migration-guide#major-breaking-changes).
You may wish to read the full migration notes for [Storybook 6 to 7](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-65x-to-700) and [Storybook 7 to 8](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-7x-to-800) before migrating. Or you can follow the instructions below and we’ll try to take care of everything for you!
## Automatic upgrade
To upgrade your Storybook:
{/* prettier-ignore-start */}
<CodeSnippets path="storybook-upgrade.md" />
{/* prettier-ignore-end */}
This will:
1. Determine that none of the [breaking changes](#major-breaking-changes) apply to your project
* If they do, you will receive instructions on how to resolve them before continuing
2. Upgrade your Storybook dependencies to the latest version
3. Run a collection of *automigrations*, which will:
* Check for common upgrade tasks
* Explain the necessary changes with links to more information
* Ask for approval, then perform the task on your behalf
### Common upgrade issues
While we'll do our best to upgrade your project automatically, there are two issues worth mentioning that you might encounter during the upgrade process:
#### `storyStoreV7:false` and `storiesOf`
If you have `storyStoreV7: false` in your `.storybook/main.js`, you will need to remove it before you're able to upgrade to Storybook 8.
If you are using the `storiesOf` API (which requires `storyStoreV7: false` in Storybook 7), you will need to either [migrate your stories to CSF](../../release-7-6/docs/migration-guide.mdx#storiesof-to-csf) or use the [new indexer API to continue creating stories dynamically](../../release-7-6/docs/migration-guide.mdx#storiesof-to-dynamically-created-stories).
#### MDX 1 to MDX 3
Storybook 8 uses MDX 3. If you're coming from MDX 1 (used by Storybook 6), there were significant breaking changes in MDX 2. Please reference our [guidance on upgrading successfully](../../release-7-6/docs/migration-guide.mdx#upgrade-mdx1-to-mdx2).
#### Missing `vite.config.js` file
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:
1. Try running the [`doctor` command](../api/cli-options.mdx#doctor) to check for common issues (such as duplicate dependencies, incompatible addons, or mismatched versions) and see suggestions for fixing them.
2. If you’re running `storybook` with the `dev` command, try using the `build` command instead. Sometimes `build` errors are more legible than `dev` errors!
3. Check [the full migration notes](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#from-version-7x-to-800), which contains an exhaustive list of noteworthy changes in Storybook 8. Many of these are already handled by automigrations when you upgrade, but not all are. It’s also possible that you’re experiencing a corner case that we’re not aware of.
4. Search [Storybook issues on GitHub](https://github.com/storybookjs/storybook/issues). If you’re seeing a problem, there’s a good chance other people are too. If so, upvote the issue, try out any workarounds described in the comments, and comment back if you have useful info to contribute.
5. If there’s no existing issue, you can [file one](https://github.com/storybookjs/storybook/issues/new/choose), ideally with a reproduction attached. We’ll be on top of Storybook 8 issues as we’re stabilizing the release.
If you prefer to debug yourself, here are a few useful things you can do to help narrow down the problem:
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.
## 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 7 and 8 (but remain backwards compatible), or best practices that should help you be more productive in the future.
### CSF 2 to CSF 3
There are [many good reasons](/blog/storybook-csf3-is-here/) to convert your stories from CSF 2 to CSF 3. We provide a codemod which, in most cases, should automatically make the code changes for you (make sure to update the glob to fit your files):
{/* prettier-ignore-start */}
<CodeSnippets path="storybook-migrate-csf-2-to-3.md" />
{/* prettier-ignore-end */}
Reference in New Issue View Git Blame Copy Permalink