From 29de79b26c030993f3b8bd69b64407350e6312f5 Mon Sep 17 00:00:00 2001 From: Ian VanSchooten Date: Thu, 12 Jan 2023 23:01:12 -0500 Subject: [PATCH 1/6] Organize 7.0 migration guide --- MIGRATION.md | 583 ++++++++++++++++++++++++++------------------------- 1 file changed, 293 insertions(+), 290 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index f50dae7b2eec..21aed3781788 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,45 +1,42 @@

Migration

- [From version 6.5.x to 7.0.0](#from-version-65x-to-700) - - [Alpha release notes](#alpha-release-notes) - [7.0 breaking changes](#70-breaking-changes) - - [Titles are statically computed](#titles-are-statically-computed) - - [Removed global client APIs](#removed-global-client-apis) - [Dropped support for Node 15 and below](#dropped-support-for-node-15-and-below) - - [React peer dependencies required](#react-peer-dependencies-required) - - [Postcss removed](#postcss-removed) - - [Vue3 replaced app export with setup](#vue3-replaced-app-export-with-setup) - - [removed auto injection of @storybook/addon-actions decorator](#removed-auto-injection-of-storybookaddon-actions-decorator) - - [register.js removed](#registerjs-removed) - - [Change of root html IDs](#change-of-root-html-ids) - - [No more default export from `@storybook/addons`](#no-more-default-export-from-storybookaddons) - [Modern browser support](#modern-browser-support) - - [No more configuration for manager](#no-more-configuration-for-manager) + - [React peer dependencies required](#react-peer-dependencies-required) - [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) - [Framework field mandatory](#framework-field-mandatory) - [frameworkOptions renamed](#frameworkoptions-renamed) - - [TypeScript: StorybookConfig type moved](#typescript-storybookconfig-type-moved) + - [Titles are statically computed](#titles-are-statically-computed) - [Framework standalone build moved](#framework-standalone-build-moved) - - [Docs modern inline rendering by default](#docs-modern-inline-rendering-by-default) + - [Change of root html IDs](#change-of-root-html-ids) + - [Stories glob matches MDX files](#stories-glob-matches-mdx-files) + - [Add strict mode](#add-strict-mode) - [Babel mode v7 exclusively](#babel-mode-v7-exclusively) - [7.0 feature flags removed](#70-feature-flags-removed) - - [CLI option `--use-npm` deprecated](#cli-option---use-npm-deprecated) + - [Core addons](#core-addons) + - [Removed auto injection of @storybook/addon-actions decorator](#removed-auto-injection-of-storybookaddon-actions-decorator) + - [Addon-backgrounds: Removed deprecated grid parameter](#addon-backgrounds-removed-deprecated-grid-parameter) + - [Addon-a11y: Removed deprecated withA11y decorator](#addon-a11y-removed-deprecated-witha11y-decorator) + - [Vite](#vite) - [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) + - [Webpack](#webpack) + - [Webpack4 support discontinued](#webpack4-support-discontinued) + - [Postcss removed](#postcss-removed) + - [Angular](#angular) + - [Dropped support for Angular 12 and below](#dropped-support-for-angular-12-and-below) + - [Svelte](#svelte) - [SvelteKit needs the `@storybook/sveltekit` framework](#sveltekit-needs-the-storybooksveltekit-framework) - - [Removed docs.getContainer and getPage parameters](#removed-docsgetcontainer-and-getpage-parameters) - - [Removed STORYBOOK\_REACT\_CLASSES global](#removed-storybook_react_classes-global) + - [Vue](#vue) + - [Vue3 replaced app export with setup](#vue3-replaced-app-export-with-setup) + - [Addon authors](#addon-authors) + - [register.js removed](#registerjs-removed) + - [No more default export from `@storybook/addons`](#no-more-default-export-from-storybookaddons) + - [No more configuration for manager](#no-more-configuration-for-manager) - [Icons API changed](#icons-api-changed) - - ['config' preset entry replaced with 'previewAnnotations'](#config-preset-entry-replaced-with-previewannotations) - - [Dropped support for Angular 12 and below](#dropped-support-for-angular-12-and-below) - - [Addon-backgrounds: Removed deprecated grid parameter](#addon-backgrounds-removed-deprecated-grid-parameter) - - [Addon-docs: Removed deprecated blocks.js entry](#addon-docs-removed-deprecated-blocksjs-entry) - - [Addon-a11y: Removed deprecated withA11y decorator](#addon-a11y-removed-deprecated-witha11y-decorator) - - [Stories glob matches MDX files](#stories-glob-matches-mdx-files) - - [Add strict mode](#add-strict-mode) - - [Removed DLL flags](#removed-dll-flags) + - [Removed global client APIs](#removed-global-client-apis) - [Docs Changes](#docs-changes) - [Standalone docs files](#standalone-docs-files) - [Referencing stories in docs files](#referencing-stories-in-docs-files) @@ -51,15 +48,22 @@ - [Default docs styles will leak into non-story user components](#default-docs-styles-will-leak-into-non-story-user-components) - [Explicit `` elements are no longer syntax highlighted](#explicit-code-elements-are-no-longer-syntax-highlighted) - [Dropped source loader / storiesOf static snippets](#dropped-source-loader--storiesof-static-snippets) + - [Removed docs.getContainer and getPage parameters](#removed-docsgetcontainer-and-getpage-parameters) + - [Addon-docs: Removed deprecated blocks.js entry](#addon-docs-removed-deprecated-blocksjs-entry) - [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) - - [7.0 Deprecations](#70-deprecations) + - [Docs modern inline rendering by default](#docs-modern-inline-rendering-by-default) + - [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) - [`ComponentStory`, `ComponentStoryObj`, `ComponentStoryFn` and `ComponentMeta` types are deprecated](#componentstory-componentstoryobj-componentstoryfn-and-componentmeta-types-are-deprecated) - [Renamed `renderToDOM` to `renderToCanvas`](#renamed-rendertodom-to-rendertocanvas) - [Renamed `XFramework` to `XRenderer`](#renamed-xframework-to-xrenderer) - [Renamed `DecoratorFn` to `Decorator`](#renamed-decoratorfn-to-decorator) + - [CLI option `--use-npm` deprecated](#cli-option---use-npm-deprecated) + - ['config' preset entry replaced with 'previewAnnotations'](#config-preset-entry-replaced-with-previewannotations) - [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) @@ -264,153 +268,12 @@ ## 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. - ### 7.0 breaking changes -#### Titles are statically computed - -Up until version 7.0, it was possible to generate the default export of a CSF story by calling a function, or mixing in variables defined in other ES Modules. For instance: - -```js -// Dynamically computed local title -const categories = { - atoms: 'Atoms', - molecules: 'Molecules', - // etc. -} - -export default { - title: `${categories.atoms}/MyComponent` -} - -// Title returned by a function -import { genDefault } from '../utils/storybook' - -export default genDefault({ - category: 'Atoms', - title: 'MyComponent', -}) -``` - -This is no longer possible in Storybook 7.0, as story titles are parsed at build time. In earlier versions, titles were mostly produced manually. Now that [CSF3 auto-title](#csf3-auto-title-improvements) is available, optimisations were made that constrain how `id` and `title` can be defined manually. - -As a result, titles cannot depend on variables or functions, and cannot be dynamically computed (even with local variables). Stories must have a static `title` property, or a static `component` property used by the [CSF3 auto-title](#csf3-auto-title-improvements) feature to compute a title. - -Likewise, the `id` property must be statically defined. The URL defined for a story in the sidebar will be statically computed, so if you dynamically add an `id` through a function call like above, the story URL will not match the one in the sidebar and the story will be unreachable. - -To opt-out of the old behavior you can set the `storyStoreV7` feature flag to `false` in `main.js`. However, a variety of performance optimizations depend on the new behavior, and the old behavior is deprecated and will be removed from Storybook in 8.0. - -```js -module.exports = { - features: { - storyStoreV7: false, - }, -}; -``` - -#### Removed global client APIs - -The `addParameters` and `addDecorator` APIs to add global decorators and parameters, exported by the various frameworks (e.g. `@storybook/react`) and `@storybook/client` were deprecated in 6.0 and have been removed in 7.0. - -Instead, use `export const parameters = {};` and `export const decorators = [];` in your `.storybook/preview.js`. Addon authors similarly should use such an export in a preview entry file (see [Preview entries](https://github.com/storybookjs/storybook/blob/next/docs/addons/writing-presets.md#preview-entries)). - #### Dropped support for Node 15 and below Storybook 7.0 requires **Node 16** or above. If you are using an older version of Node, you will need to upgrade or keep using Storybook 6 in the meantime. -#### React peer dependencies required - -Starting in 7.0, `react` and `react-dom` are now required peer dependencies of Storybook. - -Storybook uses `react` in a variety of packages. In the past, we've done various trickery hide this from non-React users. However, with stricter peer dependency handling by `npm8`, `npm`, and `yarn pnp` those tricks have started to cause problems for those users. Rather than resorting to even more complicated tricks, we are making `react` and `react-dom` required peer dependencies. - -To upgrade manually, add any version of `react` and `react-dom` as devDependencies using your package manager of choice, e.g. - -``` -npm add react react-dom --dev -``` - -#### Postcss removed - -Storybook 6.x installed postcss by default. In 7.0 built-in support has been removed. IF you need it, you can add it back using [`@storybook/addon-postcss`](https://github.com/storybookjs/addon-postcss). - -#### Vue3 replaced app export with setup - -In 6.x `@storybook/vue3` exported a Vue application instance called `app`. In 7.0, this has been replaced by a `setup` function that can be used to initialize the application in your `.storybook/preview.js`: - -Before: - -```js -import { app } from '@storybook/vue3'; -import Button from './Button.vue'; - -app.component('GlobalButton', Button); -``` - -After: - -```js -import { setup } from '@storybook/vue3'; -import Button from './Button.vue'; - -setup((app) => { - app.component('GlobalButton', Button); -}); -``` - -#### removed auto injection of @storybook/addon-actions decorator - -The `withActions` decorator is no longer automatically added to stories. This is because it is really only used in the html renderer, for all other renderers it's redundant. -If you are using the html renderer and use the `handles` parameter, you'll need to manually add the `withActions` decorator: - -```diff -import globalThis from 'global'; -+import { withActions } from '@storybook/addon-actions/decorator'; - -export default { - component: globalThis.Components.Button, - args: { - label: 'Click Me!', - }, - parameters: { - chromatic: { disable: true }, - }, -}; -export const Basic = { - parameters: { - handles: [{ click: 'clicked', contextmenu: 'right clicked' }], - }, -+ decorators: [withActions], -}; -``` - -#### register.js removed - -In SB 6.x and earlier, addons exported a `register.js` entry point by convention, and users would import this in `.storybook/manager.js`. This was [deprecated in SB 6.5](#deprecated-registerjs) - -In 7.0, most of Storybook's addons now export a `manager.js` entry point, which is automatically registered in Storybook's manager when the addon is listed in `.storybook/main.js`'s `addons` field. - -If your `.manager.js` config references `register.js` of any of the following addons, you can remove it: `a11y`, `actions`, `backgrounds`, `controls`, `interactions`, `jest`, `links`, `measure`, `outline`, `toolbars`, `viewport`. - -#### Change of root html IDs - -The root ID unto which storybook renders stories is renamed from `root` to `#storybook-root` to avoid conflicts with user's code. - -#### No more default export from `@storybook/addons` - -The default export from `@storybook/addons` has been removed. Please use the named exports instead: - -```js -import { addons } from '@storybook/addons'; -``` - -The named export has been available since 6.0 or earlier, so your updated code will be backwards-compatible with older versions of Storybook. - #### Modern browser support Starting in storybook 7.0, storybook will no longer support IE11, amongst other legacy browser versions. @@ -447,26 +310,24 @@ module.exports = { Here's an example PR to one of the storybook addons: https://github.com/storybookjs/addon-coverage/pull/3 doing just that. -#### No more configuration for manager +#### React peer dependencies required -The storybook manager is no longer built with webpack. Now it's built with esbuild. -Therefore, it's no longer possible to configure the manager. Esbuild comes preconfigured to handle importing CSS, and images. +_Has automigration_ -If you're currently loading files other than CSS or images into the manager, you'll need to make changes so the files get converted to JS before publishing your addon. +Starting in 7.0, `react` and `react-dom` are now required peer dependencies of Storybook when using addon-docs (or docs via addon-essentials). -This means the preset value `managerWebpack` is no longer respected, and should be removed from presets and `main.js` files. - -Addons that run in the manager can depend on `react` and `@storybook/*` packages directly. They do not need to be peerDependencies. -But very importantly, the build system ensures there will only be 1 version of these packages at runtime. The version will come from the `@storybook/ui` package, and not from the addon. -For this reason it's recommended to have these dependencies as `devDependencies` in your addon's `package.json`. +Storybook uses `react` in a variety of docs-related packages. In the past, we've done various trickery hide this from non-React users. However, with stricter peer dependency handling by `npm8`, `npm`, and `yarn pnp` those tricks have started to cause problems for those users. Rather than resorting to even more complicated tricks, we are making `react` and `react-dom` required peer dependencies. -The full list of packages that Storybook's manager bundler makes available for addons is here: https://github.com/storybookjs/storybook/blob/next/code/lib/ui/src/globals/types.ts +To upgrade manually, add any version of `react` and `react-dom` as devDependencies using your package manager of choice, e.g. -Addons in the manager will no longer be bundled together anymore, which means that if 1 fails, it doesn't break the whole manager. -Each addon is imported into the manager as an ESM module that's bundled separately. +``` +npm add react react-dom --dev +``` #### start-storybook / build-storybook binaries removed +_Has automigration_ + 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: `storybook dev` and `storybook 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. @@ -502,39 +363,10 @@ The new CLI commands remove the following flags: | -------- | --------------------------------------------------------------------------------------------- | | --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. - -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 upgrade 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. - #### Framework field mandatory +_Has automigration_ + 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. @@ -543,21 +375,24 @@ 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/ember` +- `@storybook/html-vite` - `@storybook/html-webpack5` - `@storybook/nextjs` +- `@storybook/preact-vite` - `@storybook/preact-webpack5` -- `@storybook/react-webpack5` - `@storybook/react-vite` +- `@storybook/react-webpack5` - `@storybook/server-webpack5` -- `@storybook/svelte-webpack5` - `@storybook/svelte-vite` +- `@storybook/svelte-webpack5` - `@storybook/sveltekit` -- `@storybook/vue-webpack5` - `@storybook/vue-vite` -- `@storybook/vue3-webpack5` +- `@storybook/vue-webpack5` - `@storybook/vue3-vite` -- `@storybook/web-components-webpack5` +- `@storybook/vue3-webpack5` - `@storybook/web-components-vite` +- `@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). @@ -574,21 +409,45 @@ module.exports = { }; ``` -#### TypeScript: StorybookConfig type moved +#### Titles are statically computed + +Up until version 7.0, it was possible to generate the default export of a CSF story by calling a function, or mixing in variables defined in other ES Modules. For instance: + +```js +// Dynamically computed local title +const categories = { + atoms: 'Atoms', + molecules: 'Molecules', + // etc. +} -If you are using TypeScript you should import the `StorybookConfig` type from your framework package. +export default { + title: `${categories.atoms}/MyComponent` +} + +// Title returned by a function +import { genDefault } from '../utils/storybook' + +export default genDefault({ + category: 'Atoms', + title: 'MyComponent', +}) +``` + +This is no longer possible in Storybook 7.0, as story titles are parsed at build time. In earlier versions, titles were mostly produced manually. Now that [CSF3 auto-title](#csf3-auto-title-improvements) is available, optimisations were made that constrain how `id` and `title` can be defined manually. + +As a result, titles cannot depend on variables or functions, and cannot be dynamically computed (even with local variables). Stories must have a static `title` property, or a static `component` property used by the [CSF3 auto-title](#csf3-auto-title-improvements) feature to compute a title. -For example: +Likewise, the `id` property must be statically defined. The URL defined for a story in the sidebar will be statically computed, so if you dynamically add an `id` through a function call like above, the story URL will not match the one in the sidebar and the story will be unreachable. -```ts -import type { StorybookConfig } from '@storybook/react-vite'; +To opt-out of the old behavior you can set the `storyStoreV7` feature flag to `false` in `main.js`. However, a variety of performance optimizations depend on the new behavior, and the old behavior is deprecated and will be removed from Storybook in 8.0. -const config: StorybookConfig = { - framework: '@storybook/react-vite', - // ... your configuration +```js +module.exports = { + features: { + storyStoreV7: false, + }, }; - -export default config; ``` #### Framework standalone build moved @@ -611,20 +470,44 @@ const options = {}; build(options).then(() => console.log('done')); ``` -#### Docs modern inline rendering by default +#### Change of root html IDs -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`: +The root ID unto which storybook renders stories is renamed from `root` to `#storybook-root` to avoid conflicts with user's code. + +#### Stories glob matches MDX files + +If you used a directory based stories glob, in 6.x it would match `.stories.js` (and other JS extensions) and `.stories.mdx` files. For instance: ```js -module.exports = { - features: { - modernInlineRender: false, - }, +// in main.js +export default { + stories: ['../path/to/directory'] +}; + +// or +export default { + stories: [{ directory: '../path/to/directory' }] +}; +``` + +In 7.0, this pattern will also match `.mdx` files (the new extension for docs files - see docs changes below). If you have `.mdx` files you don't want to appear in your storybook, either move them out of the directory, or add a `files` specifier with the old pattern (`"**/*.stories.@(mdx|tsx|ts|jsx|js)"`): + +```js +export default { + stories: [{ directory: '../path/to/directory', files: '**/*.stories.@(mdx|tsx|ts|jsx|js)' }], }; ``` +#### Add strict mode + +Starting in 7.0, Storybook's build tools add [`"use strict"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) to the compiled JS output. + +If user code in `.storybook/preview.js` or stories relies on "sloppy" mode behavior, it will need to be updated. As a workaround, it is sometimes possible to move the sloppy mode code inside a script tag in `.storybook/preview-head.html`. + #### Babel mode v7 exclusively +_Has automigration_ + Storybook now uses [Babel mode v7](#babel-mode-v7) exclusively. In 6.x, Storybook provided its own babel settings out of the box. Now, Storybook's uses your project's babel settings (`.babelrc`, `babel.config.js`, etc.) instead. In the new mode, Storybook expects you to provide a configuration file. If you want a configuration file that's equivalent to the 6.x default, you can run the following command in your project directory: @@ -649,14 +532,49 @@ module.exports = { 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. | +| 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. | +| `babelModeV7` | See [Babel mode v7 exclusively](#babel-mode-v7-exclusively) | -#### CLI option `--use-npm` deprecated +### Core addons -With increased support for more package managers (pnpm), we have introduced the `--package-manager` CLI option. Please use `--package-manager=npm` to force NPM to be used to install dependencies when running Storybook CLI commands. Other valid options are `pnpm`, `yarn1`, and `yarn2` (`yarn2` is for versions 2 and higher). +#### Removed auto injection of @storybook/addon-actions decorator + +The `withActions` decorator is no longer automatically added to stories. This is because it is really only used in the html renderer, for all other renderers it's redundant. +If you are using the html renderer and use the `handles` parameter, you'll need to manually add the `withActions` decorator: + +```diff +import globalThis from 'global'; ++import { withActions } from '@storybook/addon-actions/decorator'; + +export default { + component: globalThis.Components.Button, + args: { + label: 'Click Me!', + }, + parameters: { + chromatic: { disable: true }, + }, +}; +export const Basic = { + parameters: { + handles: [{ click: 'clicked', contextmenu: 'right clicked' }], + }, ++ decorators: [withActions], +}; +``` + +#### Addon-backgrounds: Removed deprecated grid parameter + +Starting in 7.0 the `grid.cellSize` parameter should now be `backgrounds.grid.cellSize`. This was [deprecated in SB 6.1](#deprecated-grid-parameter). + +#### Addon-a11y: Removed deprecated withA11y decorator + +We removed the deprecated `withA11y` decorator. This was [deprecated in 6.0](#removed-witha11y-decorator) + +### Vite #### Vite builder uses vite config automatically @@ -670,6 +588,38 @@ For Svelte projects this means that the `svelteOptions` property in the `main.js Previously, Storybook's Vite builder placed cache files in node_modules/.vite-storybook. However, it's more common for tools to place cached files into `node_modules/.cache`, and putting them there makes it quick and easy to clear the cache for multiple tools at once. We don't expect this change will cause any problems, but it's something that users of Storybook Vite projects should know about. It can be configured by setting `cacheDir` in `viteFinal` within `.storybook/main.js` [Storybook Vite configuration docs](https://storybook.js.org/docs/react/builders/vite#configuration)). +### Webpack + +#### 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 upgrade 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. + +#### Postcss removed + +Storybook 6.x installed postcss by default. In 7.0 built-in support has been removed for webpack-based frameworks. If you need it, you can add it back using [`@storybook/addon-postcss`](https://github.com/storybookjs/addon-postcss). + +### Angular + +#### Dropped support for Angular 12 and below + +Official [Angular 12 LTS support ends Nov 2022](https://angular.io/guide/releases#actively-supported-versions). With that, Storybook also drops its support +for Angular 12 and below. + +In order to use Storybook 7.0, you need to upgrade to at least Angular 13. + +### Svelte + #### SvelteKit needs the `@storybook/sveltekit` framework SvelteKit projects need to use the `@storybook/sveltekit` framework in the `main.js` file. Previously it was enough to just setup Storybook with Svelte+Vite, but that is no longer the case. @@ -683,87 +633,90 @@ export default { Also see the note in [Vite builder uses vite config automatically](#vite-builder-uses-vite-config-automatically) about removing `svelteOptions`. -#### Removed docs.getContainer and getPage parameters +### Vue -It is no longer possible to set `parameters.docs.getContainer()` and `getPage()`. Instead use `parameters.docs.container` or `parameters.docs.page` directly. +#### Vue3 replaced app export with setup -#### Removed STORYBOOK_REACT_CLASSES global +In 6.x `@storybook/vue3` exported a Vue application instance called `app`. In 7.0, this has been replaced by a `setup` function that can be used to initialize the application in your `.storybook/preview.js`: -This was a legacy global variable from the early days of react docgen. If you were using this variable, you can instead use docgen information which is added directly to components using `.__docgenInfo`. +Before: -#### Icons API changed +```js +import { app } from '@storybook/vue3'; +import Button from './Button.vue'; -For addon authors who use the `Icons` component, its API has been updated in Storybook 7. +app.component('GlobalButton', Button); +``` -```diff -export interface IconsProps extends ComponentProps { -- icon?: IconKey; -- symbol?: IconKey; -+ icon: IconType; -+ useSymbol?: boolean; -} +After: + +```js +import { setup } from '@storybook/vue3'; +import Button from './Button.vue'; + +setup((app) => { + app.component('GlobalButton', Button); +}); ``` -Full change here: https://github.com/storybookjs/storybook/pull/18809 +### Addon authors -#### 'config' preset entry replaced with 'previewAnnotations' +#### register.js removed -The preset field `'config'` has been replaced with `'previewAnnotations'`. `'config'` is now deprecated and will be removed in Storybook 8.0. +In SB 6.x and earlier, addons exported a `register.js` entry point by convention, and users would import this in `.storybook/manager.js`. This was [deprecated in SB 6.5](#deprecated-registerjs) -Additionally, the internal field `'previewEntries'` has been removed. If you need a preview entry, just use a `'previewAnnotations'` file and don't export anything. +In 7.0, most of Storybook's addons now export a `manager.js` entry point, which is automatically registered in Storybook's manager when the addon is listed in `.storybook/main.js`'s `addons` field. -#### Dropped support for Angular 12 and below +If your `.manager.js` config references `register.js` of any of the following addons, you can remove it: `a11y`, `actions`, `backgrounds`, `controls`, `interactions`, `jest`, `links`, `measure`, `outline`, `toolbars`, `viewport`. -Official [Angular 12 LTS support ends Nov 2022](https://angular.io/guide/releases#actively-supported-versions). With that, Storybook also drops its support -for Angular 12 and below. +#### No more default export from `@storybook/addons` -In order to use Storybook 7.0, you need to upgrade to at least Angular 13. +The default export from `@storybook/addons` has been removed. Please use the named exports instead: -#### Addon-backgrounds: Removed deprecated grid parameter +```js +import { addons } from '@storybook/addons'; +``` -Starting in 7.0 the `grid.cellSize` parameter should now be `backgrounds.grid.cellSize`. This was [deprecated in SB 6.1](#deprecated-grid-parameter). +The named export has been available since 6.0 or earlier, so your updated code will be backwards-compatible with older versions of Storybook. -#### Addon-docs: Removed deprecated blocks.js entry +#### No more configuration for manager -Removed `@storybook/addon-docs/blocks` entry. Import directly from `@storybook/blocks` instead. This was [deprecated in SB 6.3](#deprecated-scoped-blocks-imports). +The storybook manager is no longer built with webpack. Now it's built with esbuild. +Therefore, it's no longer possible to configure the manager. Esbuild comes preconfigured to handle importing CSS, and images. -#### Addon-a11y: Removed deprecated withA11y decorator +If you're currently loading files other than CSS or images into the manager, you'll need to make changes so the files get converted to JS before publishing your addon. -We removed the deprecated `withA11y` decorator. This was [deprecated in 6.0](#removed-witha11y-decorator) +This means the preset value `managerWebpack` is no longer respected, and should be removed from presets and `main.js` files. -#### Stories glob matches MDX files +Addons that run in the manager can depend on `react` and `@storybook/*` packages directly. They do not need to be peerDependencies. +But very importantly, the build system ensures there will only be 1 version of these packages at runtime. The version will come from the `@storybook/ui` package, and not from the addon. +For this reason it's recommended to have these dependencies as `devDependencies` in your addon's `package.json`. -If you used a directory based stories glob, in 6.x it would match `.stories.js` (and other JS extensions) and `.stories.mdx` files. For instance: +The full list of packages that Storybook's manager bundler makes available for addons is here: https://github.com/storybookjs/storybook/blob/next/code/lib/ui/src/globals/types.ts -```js -// in main.js -export default { - stories: ['../path/to/directory'] -}; +Addons in the manager will no longer be bundled together anymore, which means that if 1 fails, it doesn't break the whole manager. +Each addon is imported into the manager as an ESM module that's bundled separately. -// or -export default { - stories: [{ directory: '../path/to/directory' }] -}; -``` +#### Icons API changed -In 7.0, this pattern will also match `.mdx` files (the new extension for docs files - see docs changes below). If you have `.mdx` files you don't want to appear in your storybook, either move them out of the directory, or add a `files` specifier with the old pattern (`"**/*.stories.@(mdx|tsx|ts|jsx|js)"`): +For addon authors who use the `Icons` component, its API has been updated in Storybook 7. -```js -export default { - stories: [{ directory: '../path/to/directory', files: '**/*.stories.@(mdx|tsx|ts|jsx|js)' }], -}; +```diff +export interface IconsProps extends ComponentProps { +- icon?: IconKey; +- symbol?: IconKey; ++ icon: IconType; ++ useSymbol?: boolean; +} ``` -#### Add strict mode - -Starting in 7.0, Storybook's build tools add [`"use strict"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) to the compiled JS output. +Full change here: https://github.com/storybookjs/storybook/pull/18809 -If user code in `.storybook/preview.js` or stories relies on "sloppy" mode behavior, it will need to be updated. As a workaround, it is sometimes possible to move the sloppy mode code inside a script tag in `.storybook/preview-head.html`. +#### Removed global client APIs -#### Removed DLL flags +The `addParameters` and `addDecorator` APIs to add global decorators and parameters, exported by the various frameworks (e.g. `@storybook/react`) and `@storybook/client` were deprecated in 6.0 and have been removed in 7.0. -Earlier versions of Storybook used Webpack DLLs as a performance crutch. In 6.1, we've removed Storybook's built-in DLLs and have deprecated the command-line parameters `--no-dll` and `--ui-dll`. In 7.0 those options are removed. +Instead, use `export const parameters = {};` and `export const decorators = [];` in your `.storybook/preview.js`. Addon authors similarly should use such an export in a preview entry file (see [Preview entries](https://github.com/storybookjs/storybook/blob/next/docs/addons/writing-presets.md#preview-entries)). ### Docs Changes @@ -859,7 +812,7 @@ You can change the default template in the same way as in 6.x, using the `docs.p #### Configuring the Docs Container -As in 6.x, you can override the docs container to configure docs further. This the container that each docs entry is rendered inside: +As in 6.x, you can override the docs container to configure docs further. This is the container that each docs entry is rendered inside: ```js // in preview.js @@ -999,6 +952,14 @@ module.exports = { }; ``` +#### Removed docs.getContainer and getPage parameters + +It is no longer possible to set `parameters.docs.getContainer()` and `getPage()`. Instead use `parameters.docs.container` or `parameters.docs.page` directly. + +#### Addon-docs: Removed deprecated blocks.js entry + +Removed `@storybook/addon-docs/blocks` entry. Import directly from `@storybook/blocks` instead. This was [deprecated in SB 6.3](#deprecated-scoped-blocks-imports). + #### Dropped addon-docs manual babel configuration Addon-docs previously accepted `configureJsx` and `mdxBabelOptions` options, which allowed full customization of the babel options used to process markdown and mdx files. This has been simplified in 7.0, with a new option, `jsxOptions`, which can be used to customize the behavior of `@babel/preset-react`. @@ -1013,7 +974,39 @@ Running play functions in docs is generally tricky, as they can steal focus and If your story depends on a play function to render correctly, _and_ you are confident the function autoplaying won't mess up your docs, you can set `parameters.docs.autoplay = true` to have it auto play. -### 7.0 Deprecations +#### 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, + }, +}; +``` + +#### Removed STORYBOOK_REACT_CLASSES global + +This was a legacy global variable from the early days of react docgen. If you were using this variable, you can instead use docgen information which is added directly to components using `.__docgenInfo`. + +### 7.0 Deprecations and default changes + +#### 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. #### `Story` type deprecated @@ -1129,6 +1122,16 @@ import type { Args, Decorator } from '@storybook/react'; const withLocale: Decorator = (Story, { args }) => // args has type { [name: string]: any } ``` +#### CLI option `--use-npm` deprecated + +With increased support for more package managers (pnpm), we have introduced the `--package-manager` CLI option. Please use `--package-manager=npm` to force NPM to be used to install dependencies when running Storybook CLI commands. Other valid options are `pnpm`, `yarn1`, and `yarn2` (`yarn2` is for versions 2 and higher). + +#### 'config' preset entry replaced with 'previewAnnotations' + +The preset field `'config'` has been replaced with `'previewAnnotations'`. `'config'` is now deprecated and will be removed in Storybook 8.0. + +Additionally, the internal field `'previewEntries'` has been removed. If you need a preview entry, just use a `'previewAnnotations'` file and don't export anything. + ## From version 6.4.x to 6.5.0 ### Vue 3 upgrade From 07be6fdc43cc55cfef2c118ec012de0976c8b1ae Mon Sep 17 00:00:00 2001 From: Ian VanSchooten Date: Thu, 12 Jan 2023 23:02:17 -0500 Subject: [PATCH 2/6] Remove docs for modernInlineRender --- MIGRATION.md | 13 ------------- .../preview-api/src/modules/preview-web/Preview.tsx | 2 +- docs/configure/overview.md | 1 - 3 files changed, 1 insertion(+), 15 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 21aed3781788..069e73e882ac 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -53,7 +53,6 @@ - [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) - - [Docs modern inline rendering by default](#docs-modern-inline-rendering-by-default) - [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) @@ -974,18 +973,6 @@ Running play functions in docs is generally tricky, as they can steal focus and If your story depends on a play function to render correctly, _and_ you are confident the function autoplaying won't mess up your docs, you can set `parameters.docs.autoplay = true` to have it auto play. -#### 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, - }, -}; -``` - #### Removed STORYBOOK_REACT_CLASSES global This was a legacy global variable from the early days of react docgen. If you were using this variable, you can instead use docgen information which is added directly to components using `.__docgenInfo`. diff --git a/code/lib/preview-api/src/modules/preview-web/Preview.tsx b/code/lib/preview-api/src/modules/preview-web/Preview.tsx index f1c2da44c15b..fa0a12a0d246 100644 --- a/code/lib/preview-api/src/modules/preview-web/Preview.tsx +++ b/code/lib/preview-api/src/modules/preview-web/Preview.tsx @@ -306,7 +306,7 @@ export class Preview { await Promise.all(this.storyRenders.filter((r) => r.id === storyId).map((r) => r.remount())); } - // Used by docs' modernInlineRender to render a story to a given element + // Used by docs to render a story to a given element // Note this short-circuits the `prepare()` phase of the StoryRender, // main to be consistent with the previous behaviour. In the future, // we will change it to go ahead and load the story, which will end up being diff --git a/docs/configure/overview.md b/docs/configure/overview.md index 36bd1dbfb066..651ff7c10d95 100644 --- a/docs/configure/overview.md +++ b/docs/configure/overview.md @@ -49,7 +49,6 @@ Additionally, you can also provide additional feature flags to your Storybook co | `emotionAlias` | Provides backwards compatibility for Emotion. See the [migration documentation](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#emotion11-quasi-compatibility) for context.
`features: { emotionAlias: false }` | | `babelModeV7` | Enables the new [Babel configuration](./babel.md#v7-mode) mode for Storybook.
`features: { babelModeV7: true }` | | `postcss` | Disables the implicit PostCSS warning. See the [migration documentation](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-implicit-postcss-loader) for context.
`features: { postcss: false }` | -| `modernInlineRender` | Enables Storybook's modern inline rendering mode.
`features: { modernInlineRender: false }` | | `previewMdx2` | Enables experimental support for [MDX 2](../writing-docs/mdx.md#mdx-2).
`features: { previewMdx2: true }` | ## Configure story loading From e3eaac30c6222301c081d52f933daa57e647855d Mon Sep 17 00:00:00 2001 From: Ian VanSchooten Date: Thu, 12 Jan 2023 23:14:12 -0500 Subject: [PATCH 3/6] Add note up front about upgrade script --- MIGRATION.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/MIGRATION.md b/MIGRATION.md index 069e73e882ac..2b7f990e9157 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -267,6 +267,8 @@ ## From version 6.5.x to 7.0.0 +A number of these changes can be made automatically by the storybook cli. To take advantage of these "automigrations", run `npx storybook@next upgrade --prerelease` or `pnpx storybook@next upgrade --prerelease`. + ### 7.0 breaking changes #### Dropped support for Node 15 and below From 213b2319304f4eff93dd4d09ad67644429ee017c Mon Sep 17 00:00:00 2001 From: Ian VanSchooten Date: Fri, 13 Jan 2023 09:35:18 -0500 Subject: [PATCH 4/6] Group framework changes --- MIGRATION.md | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 2b7f990e9157..e7d37ba591ad 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -25,12 +25,10 @@ - [Webpack](#webpack) - [Webpack4 support discontinued](#webpack4-support-discontinued) - [Postcss removed](#postcss-removed) - - [Angular](#angular) - - [Dropped support for Angular 12 and below](#dropped-support-for-angular-12-and-below) - - [Svelte](#svelte) - - [SvelteKit needs the `@storybook/sveltekit` framework](#sveltekit-needs-the-storybooksveltekit-framework) - - [Vue](#vue) - - [Vue3 replaced app export with setup](#vue3-replaced-app-export-with-setup) + - [Framework-specific](#framework-specific) + - [Angular: dropped support for Angular 12 and below](#angular-dropped-support-for-angular-12-and-below) + - [SvelteKit: needs the `@storybook/sveltekit` framework](#sveltekit-needs-the-storybooksveltekit-framework) + - [Vue3: replaced app export with setup](#vue3-replaced-app-export-with-setup) - [Addon authors](#addon-authors) - [register.js removed](#registerjs-removed) - [No more default export from `@storybook/addons`](#no-more-default-export-from-storybookaddons) @@ -610,18 +608,16 @@ During the 7.0 dev cycle we will be updating this section with useful resources Storybook 6.x installed postcss by default. In 7.0 built-in support has been removed for webpack-based frameworks. If you need it, you can add it back using [`@storybook/addon-postcss`](https://github.com/storybookjs/addon-postcss). -### Angular +### Framework-specific -#### Dropped support for Angular 12 and below +#### Angular: dropped support for Angular 12 and below Official [Angular 12 LTS support ends Nov 2022](https://angular.io/guide/releases#actively-supported-versions). With that, Storybook also drops its support for Angular 12 and below. In order to use Storybook 7.0, you need to upgrade to at least Angular 13. -### Svelte - -#### SvelteKit needs the `@storybook/sveltekit` framework +#### SvelteKit: needs the `@storybook/sveltekit` framework SvelteKit projects need to use the `@storybook/sveltekit` framework in the `main.js` file. Previously it was enough to just setup Storybook with Svelte+Vite, but that is no longer the case. @@ -634,9 +630,7 @@ export default { Also see the note in [Vite builder uses vite config automatically](#vite-builder-uses-vite-config-automatically) about removing `svelteOptions`. -### Vue - -#### Vue3 replaced app export with setup +#### Vue3: replaced app export with setup In 6.x `@storybook/vue3` exported a Vue application instance called `app`. In 7.0, this has been replaced by a `setup` function that can be used to initialize the application in your `.storybook/preview.js`: From 29c0e6e4604a380698daf8924bc7ea68375b121e Mon Sep 17 00:00:00 2001 From: Ian VanSchooten Date: Tue, 17 Jan 2023 14:29:44 -0500 Subject: [PATCH 5/6] Capitalizations --- MIGRATION.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index e7d37ba591ad..1ea98433333b 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -20,7 +20,7 @@ - [Addon-backgrounds: Removed deprecated grid parameter](#addon-backgrounds-removed-deprecated-grid-parameter) - [Addon-a11y: Removed deprecated withA11y decorator](#addon-a11y-removed-deprecated-witha11y-decorator) - [Vite](#vite) - - [Vite builder uses vite config automatically](#vite-builder-uses-vite-config-automatically) + - [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) - [Webpack](#webpack) - [Webpack4 support discontinued](#webpack4-support-discontinued) @@ -265,7 +265,7 @@ ## From version 6.5.x to 7.0.0 -A number of these changes can be made automatically by the storybook cli. To take advantage of these "automigrations", run `npx storybook@next upgrade --prerelease` or `pnpx storybook@next upgrade --prerelease`. +A number of these changes can be made automatically by the Storybook CLI. To take advantage of these "automigrations", run `npx storybook@next upgrade --prerelease` or `pnpx storybook@next upgrade --prerelease`. ### 7.0 breaking changes @@ -275,11 +275,11 @@ Storybook 7.0 requires **Node 16** or above. If you are using an older version o #### Modern browser support -Starting in storybook 7.0, storybook will no longer support IE11, amongst other legacy browser versions. +Starting in Storybook 7.0, Storybook will no longer support IE11, amongst other legacy browser versions. We now transpile our code with a target of `chrome >= 100` and node code is transpiled with a target of `node >= 16`. This means code-features such as (but not limited to) `async/await`, arrow-functions, `const`,`let`, etc will exist in the code at runtime, and thus the runtime environment must support it. -Not just the runtime needs to support it, but some legacy loaders for webpack or other transpilation tools might need to be updated as well. For example, certain versions of webpack 4 had parsers that could not parse the new syntax (e.g. optional chaining). +Not just the runtime needs to support it, but some legacy loaders for Webpack or other transpilation tools might need to be updated as well. For example, certain versions of Webpack 4 had parsers that could not parse the new syntax (e.g. optional chaining). Some addons or libraries might depended on this legacy browser support, and thus might break. You might get an error like: @@ -307,7 +307,7 @@ module.exports = { }; ``` -Here's an example PR to one of the storybook addons: https://github.com/storybookjs/addon-coverage/pull/3 doing just that. +Here's an example PR to one of the Storybook addons: https://github.com/storybookjs/addon-coverage/pull/3 doing just that. #### React peer dependencies required @@ -329,9 +329,9 @@ _Has automigration_ 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: `storybook dev` and `storybook 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. +In SB7.0, we've removed these binaries and replaced them with new commands in Storybook's CLI: `storybook dev` and `storybook 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`: +A typical Storybook project includes two scripts in your projects `package.json`: ```json { @@ -471,7 +471,7 @@ build(options).then(() => console.log('done')); #### Change of root html IDs -The root ID unto which storybook renders stories is renamed from `root` to `#storybook-root` to avoid conflicts with user's code. +The root ID unto which Storybook renders stories is renamed from `root` to `#storybook-root` to avoid conflicts with user's code. #### Stories glob matches MDX files @@ -575,11 +575,11 @@ We removed the deprecated `withA11y` decorator. This was [deprecated in 6.0](#re ### Vite -#### Vite builder uses vite config automatically +#### Vite builder uses Vite config automatically When using a [Vite-based framework](#framework-field-mandatory), Storybook will automatically use your `vite.config.(ctm)js` config file starting in 7.0. -Some settings will be overridden by storybook so that it can function properly, and the merged settings can be modified using `viteFinal` in `.storybook/main.js` (see the [Storybook Vite configuration docs](https://storybook.js.org/docs/react/builders/vite#configuration)). -If you were using `viteFinal` in 6.5 to simply merge in your project's standard vite config, you can now remove it. +Some settings will be overridden by Storybook so that it can function properly, and the merged settings can be modified using `viteFinal` in `.storybook/main.js` (see the [Storybook Vite configuration docs](https://storybook.js.org/docs/react/builders/vite#configuration)). +If you were using `viteFinal` in 6.5 to simply merge in your project's standard Vite config, you can now remove it. For Svelte projects this means that the `svelteOptions` property in the `main.js` config should be omitted, as it will be loaded automatically via the project's `vite.config.js`. An exception to this is when the project needs different Svelte options for Storybook than the Vite config provides for the application itself. @@ -599,14 +599,14 @@ If you are running into errors, you can upgrade your project to Webpack5 or you 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 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 upgrade 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. #### Postcss removed -Storybook 6.x installed postcss by default. In 7.0 built-in support has been removed for webpack-based frameworks. If you need it, you can add it back using [`@storybook/addon-postcss`](https://github.com/storybookjs/addon-postcss). +Storybook 6.x installed postcss by default. In 7.0 built-in support has been removed for Webpack-based frameworks. If you need it, you can add it back using [`@storybook/addon-postcss`](https://github.com/storybookjs/addon-postcss). ### Framework-specific @@ -628,7 +628,7 @@ export default { }; ``` -Also see the note in [Vite builder uses vite config automatically](#vite-builder-uses-vite-config-automatically) about removing `svelteOptions`. +Also see the note in [Vite builder uses Vite config automatically](#vite-builder-uses-vite-config-automatically) about removing `svelteOptions`. #### Vue3: replaced app export with setup @@ -676,7 +676,7 @@ The named export has been available since 6.0 or earlier, so your updated code w #### No more configuration for manager -The storybook manager is no longer built with webpack. Now it's built with esbuild. +The Storybook manager is no longer built with Webpack. Now it's built with esbuild. Therefore, it's no longer possible to configure the manager. Esbuild comes preconfigured to handle importing CSS, and images. If you're currently loading files other than CSS or images into the manager, you'll need to make changes so the files get converted to JS before publishing your addon. @@ -923,11 +923,11 @@ const a = 'This is still a styled code block.'; #### Dropped source loader / storiesOf static snippets -In SB 6.x, Storybook Docs used a webpack loader called `source-loader` to help display static code snippets. This was configurable using the `options.sourceLoaderOptions` field. +In SB 6.x, Storybook Docs used a Webpack loader called `source-loader` to help display static code snippets. This was configurable using the `options.sourceLoaderOptions` field. In SB 7.0, we've moved to a faster, simpler alternative called `csf-plugin` that **only supports CSF**. It is configurable using the `options.csfPluginOptions` field. -If you're using `storiesOf` and want to restore the previous behavior, you can add `source-loader` by hand to your webpack config using the following snippet in `main.js`: +If you're using `storiesOf` and want to restore the previous behavior, you can add `source-loader` by hand to your Webpack config using the following snippet in `main.js`: ```js module.exports = { @@ -961,7 +961,7 @@ Addon-docs previously accepted `configureJsx` and `mdxBabelOptions` options, whi #### Dropped addon-docs manual configuration -Storybook Docs 5.x shipped with instructions for how to manually configure webpack and storybook without the use of Storybook's "presets" feature. Over time, these docs went out of sync. Now in Storybook 7 we have removed support for manual configuration entirely. +Storybook Docs 5.x shipped with instructions for how to manually configure Webpack and Storybook without the use of Storybook's "presets" feature. Over time, these docs went out of sync. Now in Storybook 7 we have removed support for manual configuration entirely. #### Autoplay in docs @@ -1168,7 +1168,7 @@ SB6.5 moves framework specializations (e.g. ArgType inference, dynamic snippet r This change should not require any specific migrations on your part if you are using the docs addon as described in the documentation. However, if you are using `react-docgen` or `react-docgen-typescript` information in some custom way outside of `addon-docs`, you should be aware of this change. -In SB6.4, `@storybook/react` added `react-docgen` to its babel settings and `react-docgen-typescript` to its webpack settings. In SB6.5, this only happens if you are using `addon-docs` or `addon-controls`, either directly or indirectly through `addon-essentials`. If you're not using either of those addons, but require that information for some other addon, please configure that manually in your `.storybook/main.js` configuration. You can see the docs configuration here: https://github.com/storybookjs/storybook/blob/next/code/presets/react-webpack/src/framework-preset-react-docs.ts +In SB6.4, `@storybook/react` added `react-docgen` to its babel settings and `react-docgen-typescript` to its Webpack settings. In SB6.5, this only happens if you are using `addon-docs` or `addon-controls`, either directly or indirectly through `addon-essentials`. If you're not using either of those addons, but require that information for some other addon, please configure that manually in your `.storybook/main.js` configuration. You can see the docs configuration here: https://github.com/storybookjs/storybook/blob/next/code/presets/react-webpack/src/framework-preset-react-docs.ts ### Opt-in MDX2 support @@ -1301,7 +1301,7 @@ npx sb@next automigrate ``` -The automigration suite also runs when you create a new project (`sb init`) or when you update storybook (`sb upgrade`). +The automigration suite also runs when you create a new project (`sb init`) or when you update Storybook (`sb upgrade`). ### CRA5 upgrade @@ -1313,7 +1313,7 @@ npx sb@next automigrate ``` -Or you can do the following steps manually to force Storybook to use webpack 5 for building your project: +Or you can do the following steps manually to force Storybook to use Webpack 5 for building your project: ```shell yarn add @storybook/builder-webpack5 @storybook/manager-webpack5 --dev From 743b4b285784281027198014f3e4ce6efa5d7a4e Mon Sep 17 00:00:00 2001 From: Ian VanSchooten Date: Tue, 17 Jan 2023 14:37:08 -0500 Subject: [PATCH 6/6] Re-add sections lost in rebase --- MIGRATION.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/MIGRATION.md b/MIGRATION.md index 1ea98433333b..f4521113c3bf 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -8,6 +8,7 @@ - [start-storybook / build-storybook binaries removed](#start-storybook--build-storybook-binaries-removed) - [Framework field mandatory](#framework-field-mandatory) - [frameworkOptions renamed](#frameworkoptions-renamed) + - [TypeScript: StorybookConfig type moved](#typescript-storybookconfig-type-moved) - [Titles are statically computed](#titles-are-statically-computed) - [Framework standalone build moved](#framework-standalone-build-moved) - [Change of root html IDs](#change-of-root-html-ids) @@ -25,6 +26,7 @@ - [Webpack](#webpack) - [Webpack4 support discontinued](#webpack4-support-discontinued) - [Postcss removed](#postcss-removed) + - [Removed DLL flags](#removed-dll-flags) - [Framework-specific](#framework-specific) - [Angular: dropped support for Angular 12 and below](#angular-dropped-support-for-angular-12-and-below) - [SvelteKit: needs the `@storybook/sveltekit` framework](#sveltekit-needs-the-storybooksveltekit-framework) @@ -408,6 +410,21 @@ module.exports = { }; ``` +#### TypeScript: StorybookConfig type moved + +If you are using TypeScript you should import the `StorybookConfig` type from your framework package. + +For example: + +```ts +import type { StorybookConfig } from '@storybook/react-vite'; +const config: StorybookConfig = { + framework: '@storybook/react-vite', + // ... your configuration +}; +export default config; +``` + #### Titles are statically computed Up until version 7.0, it was possible to generate the default export of a CSF story by calling a function, or mixing in variables defined in other ES Modules. For instance: @@ -608,6 +625,10 @@ During the 7.0 dev cycle we will be updating this section with useful resources Storybook 6.x installed postcss by default. In 7.0 built-in support has been removed for Webpack-based frameworks. If you need it, you can add it back using [`@storybook/addon-postcss`](https://github.com/storybookjs/addon-postcss). +#### Removed DLL flags + +Earlier versions of Storybook used Webpack DLLs as a performance crutch. In 6.1, we've removed Storybook's built-in DLLs and have deprecated the command-line parameters `--no-dll` and `--ui-dll`. In 7.0 those options are removed. + ### Framework-specific #### Angular: dropped support for Angular 12 and below