From 9945912f4c39e7058c6dc28f2ca0d76482d38c40 Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Tue, 31 May 2022 16:59:41 +0800 Subject: [PATCH 1/3] Add initial 7.0 migration notes --- MIGRATION.md | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 143 insertions(+), 2 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 2d5886acb151..1f2a0fe2ae93 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,9 +1,17 @@

Migration

- [From version 6.5.x to 7.0.0](#from-version-65x-to-700) + - [Alpha release notes](#alpha-release-notes) - [Breaking changes](#breaking-changes) + - [start-storybook / build-storybook binaries removed](#start-storybook--build-storybook-binaries-removed) + - [storyStoreV7 enabled by default](#storystorev7-enabled-by-default) + - [Webpack4 support discontinued](#webpack4-support-discontinued) + - [Modern ESM / IE11 support discontinued](#modern-esm--ie11-support-discontinued) - [Framework field mandatory](#framework-field-mandatory) - [frameworkOptions renamed](#frameworkoptions-renamed) + - [Docs modern inline rendering by default](#docs-modern-inline-rendering-by-default) + - [Babel mode v7 by default](#babel-mode-v7-by-default) + - [7.0 feature flags removed](#70-feature-flags-removed) - [From version 6.4.x to 6.5.0](#from-version-64x-to-650) - [Vue 3 upgrade](#vue-3-upgrade) - [React18 new root API](#react18-new-root-api) @@ -207,11 +215,100 @@ ## From version 6.5.x to 7.0.0 +### Alpha release notes + +Storybook 7.0 is in early alpha. During the alpha, we are making a large number of breaking changes. We may also break the breaking changes based on what we learn during the development cycle. When 7.0 goes to beta, we will start stabilizing and adding various auto-migrations to help users upgrade more easily. + +In the meantime, these migration notes are the best available documentation on things you should know upgrading to 7.0. + ### Breaking changes +#### start-storybook / build-storybook binaries removed + +SB6.x framework packages shipped binaries called `start-storybook` and `build-storybook`. + +In SB7.0, we've removed these binaries and replaced them with new commands in Storybook's CLI: `sb dev` and `sb build`. These commands will look for the `framework` field in your `.storybook/main.js` config--[which is now required](#framework-field-mandatory)--and use that to determine how to start/build your storybook. The benefit of this change is that it is now possible to install multiple frameworks in a project without having to worry about hoisting issues. + +A typical storybook project includes two scripts in your projects `package.json`: + +```json +{ + "scripts": { + "storybook": "start-storybook ", + "build-storybook": "build-storybook " + } +} +``` + +To convert this project to 7.0: + +```json +{ + "scripts": { + "storybook": "sb dev ", + "build-storybook": "sb build " + }, + "devDependencies": { + "sb": "next" + } +} +``` + +#### storyStoreV7 enabled by default + +SB6.4 introduced [Story Store V7](#story-store-v7), an optimization which allows code splitting for faster build and load times. This was an experimental, opt-in change and you can read more about it in [the migration notes below](#story-store-v7). TLDR: you can't use the legacy `storiesOf` API or dynamic titles in CSF. + +Now in 7.0, Story Store V7 is the default. You can opt-out of it by setting the feature flag in `.storybook/main.js`: + +```js +module.exports = { + features: { + storyStoreV7: false, + }, +}; +``` + +During the 7.0 dev cycle we will be preparing recommendations and utilities to make it easier for `storiesOf` users to upgrade. + +#### Webpack4 support discontinued + +SB7.0 no longer supports Webpack4. + +Depending on your project specifics, it might be possible to run your Storybook using the webpack5 builder without error. + +If you are running into errors, you can upgrade your project to Webpack5 or you can try debugging those errors. + +To upgrade: + +- If you're configuring webpack directly, see the Webpack5 [release announcement](https://webpack.js.org/blog/2020-10-10-webpack-5-release/) and [migration guide](https://webpack.js.org/migrate/5). +- If you're using Create React App, see the [migration notes](https://github.com/facebook/create-react-app/blob/main/CHANGELOG.md#migrating-from-40x-to-500) to ugprade from V4 (Webpack4) to 5 + +During the 7.0 dev cycle we will be updating this section with useful resources as we run across them. + +#### Modern ESM / IE11 support discontinued + +SB7.0 compiles to modern ESM, meaning that IE11 is no longer supported. Over the course of the 7.0 dev cycle we will create recommendations for users who still require IE support. + #### Framework field mandatory In 6.4 we introduced a new `main.js` field called [`framework`](#mainjs-framework-field). Starting in 7.0, this field is mandatory. +The value of the `framework` field has also changed. + +In 6.4, valid values included `@storybook/react`, `@storybook/vue`, etc. + +In 7.0, frameworks also specify the builder to be used. For example, The current list of frameworks include: + +- `@storybook/angular` +- `@storybook/html-webpack5` +- `@storybook/preact-webpack5` +- `@storybook/react-webpack5` +- `@storybook/server-webpack5` +- `@storybook/svelte-webpack5` +- `@storybook/vue-webpack5` +- `@storybook/vue3-webpack5` +- `@storybook/web-components-webpack5` + +We will be expanding this list over the course of the 7.0 development cycle. More info on the rationale here: [Frameworks RFC](https://www.notion.so/chromatic-ui/Frameworks-RFC-89f8aafe3f0941ceb4c24683859ed65c). #### frameworkOptions renamed @@ -220,12 +317,54 @@ In 7.0, the `main.js` fields `reactOptions` and `angularOptions` have been renam ```js module.exports = { framework: { - name: '@storybook/react', + name: '@storybook/react-webpack5', options: { fastRefresh: true }; } } ``` +#### Docs modern inline rendering by default + +Storybook docs has a new rendering mode called "modern inline rendering" which unifies the way stories are rendered in Docs mode and in the canvas (aka story mode). It is still being stabilized in 7.0 dev cycle. If you run into trouble with inline rendering in docs, you can opt out of modern inline rendering in your `.storybook/main.js`: + +```js +module.exports = { + features: { + modernInlineRender: false, + }, +}; +``` + +#### Babel mode v7 by default + +Storybook now uses your project babel configuration differently as [described below in Babel Mode v7](#babel-mode-v7). This is now the default. To opt-out: + +```js +module.exports = { + features: { + babelModeV7: false, + }, +}; +``` + +#### 7.0 feature flags removed + +Storybook uses temporary feature flags to opt-in to future breaking changes or opt-in to legacy behaviors. For example: + +```js +module.exports = { + features: { + emotionAlias: false, + }, +}; +``` + +In 7.0 we've removed the following feature flags: + +| flag | migration instructions | +| -------------- | ---------------------------------------------------- | +| `emotionAlias` | This flag is no longer needed and should be deleted. | + ## From version 6.4.x to 6.5.0 ### Vue 3 upgrade @@ -391,6 +530,7 @@ In 6.5, the final titles would be: - `Title.stories.js` => `Custom/Bar` + ## From version 6.3.x to 6.4.0 ### Automigrate @@ -2934,4 +3074,5 @@ If you **are** using these addons, it takes two steps to migrate: import { action } from '@storybook/addon-actions'; import { linkTo } from '@storybook/addon-links'; ``` - \ No newline at end of file + + From 859754c842fda7bdcdb555a9d2774f8936bdd48d Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Tue, 31 May 2022 20:40:49 +0800 Subject: [PATCH 2/3] Migration for removed CLI flags --- MIGRATION.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/MIGRATION.md b/MIGRATION.md index 1f2a0fe2ae93..8a4000089304 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -254,6 +254,12 @@ To convert this project to 7.0: } ``` +The new CLI commands remove the following flags: + +| flag | migration | +| -------- | --------------------------------------------------------------------------------------------- | +| --modern | No migration needed. [All ESM code is modern in SB7](#modern-esm--ie11-support-discontinued). | + #### storyStoreV7 enabled by default SB6.4 introduced [Story Store V7](#story-store-v7), an optimization which allows code splitting for faster build and load times. This was an experimental, opt-in change and you can read more about it in [the migration notes below](#story-store-v7). TLDR: you can't use the legacy `storiesOf` API or dynamic titles in CSF. From f6a58081764373e78fcbf97aff1be73aa1b69084 Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Thu, 2 Jun 2022 17:43:55 +0800 Subject: [PATCH 3/3] Add breakingChangesV7 to removed feature flags --- MIGRATION.md | 1 + 1 file changed, 1 insertion(+) diff --git a/MIGRATION.md b/MIGRATION.md index 8a4000089304..61bd8f568d13 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -370,6 +370,7 @@ In 7.0 we've removed the following feature flags: | flag | migration instructions | | -------------- | ---------------------------------------------------- | | `emotionAlias` | This flag is no longer needed and should be deleted. | +| `breakingChangesV7` | This flag is no longer needed and should be deleted. | ## From version 6.4.x to 6.5.0