mirror of
https://github.com/storybookjs/storybook.git
synced 2025-03-16 05:03:11 +08:00
Merge pull request #22713 from storybookjs/shilman/document-v7-sort-change
Document v7 storySort changes
This commit is contained in:
jonniebigodes
GitHub
commit
1328d492f5
45
MIGRATION.md
45
MIGRATION.md
@ -122,6 +122,7 @@
|
||||
- [Main.js framework field](#mainjs-framework-field)
|
||||
- [Using the v7 store](#using-the-v7-store)
|
||||
- [v7-style story sort](#v7-style-story-sort)
|
||||
- [v7 default sort behavior](#v7-default-sort-behavior)
|
||||
- [v7 Store API changes for addon authors](#v7-store-api-changes-for-addon-authors)
|
||||
- [Storyshots compatibility in the v7 store](#storyshots-compatibility-in-the-v7-store)
|
||||
- [Emotion11 quasi-compatibility](#emotion11-quasi-compatibility)
|
||||
@ -511,7 +512,6 @@ Storybook 7 introduces the concept of `frameworks`, which abstracts configuratio
|
||||
> Note:
|
||||
> All of the following changes can be done automatically either via `npx storybook@latest upgrade --prerelease` or via the `npx storybook@latest automigrate` command. It's highly recommended to use these commands, which will tell you exactly what to do.
|
||||
|
||||
|
||||
##### Available framework packages
|
||||
|
||||
In 7.0, `frameworks` combine a `renderer` and a `builder`, with the exception of a few packages that do not contain multiple builders, such as `@storybook/angular`, which only has Webpack 5 support.
|
||||
@ -675,7 +675,7 @@ import type { StorybookConfig } from '@storybook/react-vite';
|
||||
const config: StorybookConfig = {
|
||||
framework: {
|
||||
name: '@storybook/react-vite',
|
||||
options: {}
|
||||
options: {},
|
||||
},
|
||||
// ... your configuration
|
||||
};
|
||||
@ -1126,7 +1126,7 @@ Storybook 7 adds 2 new packages for addon authors to use: `@storybook/preview-ap
|
||||
These 2 packages replace `@storybook/addons`.
|
||||
|
||||
When adding addons to storybook, you can (for example) add panels:
|
||||
|
||||
|
||||
```js
|
||||
import { addons } from '@storybook/manager-api';
|
||||
|
||||
@ -1141,7 +1141,7 @@ The `addons` export is now a named export only, there's no default export anymor
|
||||
|
||||
The package `@storybook/addons` is still available, but it's only for backwards compatibility. It's not recommended to use it anymore.
|
||||
|
||||
It's also been used by addon creators to gain access to a few APIs like `makeDecorator`.
|
||||
It's also been used by addon creators to gain access to a few APIs like `makeDecorator`.
|
||||
These APIs are now available in `@storybook/preview-api`.
|
||||
|
||||
Storybook users have had access to a few storybook-lifecycle hooks such as `useChannel`, `useParameter`, `useStorybookState`;
|
||||
@ -1179,7 +1179,6 @@ It should no longer depend on `@storybook/addons`, but instead on `@storybook/pr
|
||||
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`.
|
||||
So if you use any of these packages, please import what you need from `@storybook/preview-api` instead.
|
||||
|
||||
|
||||
Storybook 7 will prepare manager-code for the browser using ESbuild (before it was using a combination of webpack + babel).
|
||||
This is a very important change, though it will not affect most addons.
|
||||
It means that when creating custom addons, particularly custom addons within the repo in which they are consumed,
|
||||
@ -1209,17 +1208,19 @@ All of storybook's core addons have been updated and are ready to use with Story
|
||||
We're working with the community to update the most popular addons.
|
||||
But if you're using an addon that hasn't been updated yet, it might not work.
|
||||
|
||||
It's possible for example for older addons to use APIs that are no longer available in Storybook 7.
|
||||
It's possible for example for older addons to use APIs that are no longer available in Storybook 7.
|
||||
Your addon might not show upside of the storybook (manager) UI, or storybook might fail to start entirely.
|
||||
|
||||
When this happens to you please open an issue on the addon's repo, and ask the addon author to update their addon to be compatible with Storybook 7.
|
||||
It's also useful for the storybook team to know which addons are not yet compatible, so please open an issue on the storybook repo as well; particularly if the addon is popular and causes a critical failure.
|
||||
|
||||
Here's a list of popular addons that are known not to be compatible with Storybook 7 yet:
|
||||
|
||||
- [ ] [storybook-addon-jsx](https://github.com/storybookjs/addon-jsx)
|
||||
- [ ] [storybook-addon-dark-mode](https://github.com/hipstersmoothie/storybook-dark-mode)
|
||||
|
||||
Though storybook should de-duplicate storybook packages, storybook CLI's `upgrade` command will warn you when you have multiple storybook-dependencies, because it is a possibility that this causes addons/storybook to not work, so when running into issues, please run this:
|
||||
|
||||
```
|
||||
npx sb upgrade
|
||||
```
|
||||
@ -2184,10 +2185,40 @@ function storySort(a, b) {
|
||||
```
|
||||
|
||||
**NOTE:** v7-style sorting is statically analyzed by Storybook, which puts a variety of constraints versus v6:
|
||||
- Sorting must be specified in the user's `.storybook/preview.js`. It cannot be specified by an addon or preset.
|
||||
|
||||
- Sorting must be specified in the user's `.storybook/preview.js`. It cannot be specified by an addon or preset.
|
||||
- The `preview.js` export should not be generated by a function.
|
||||
- `storySort` must be a self-contained function that does not reference external variables.
|
||||
|
||||
#### v7 default sort behavior
|
||||
|
||||
The behavior of the default `storySort` function has also changed in v7 thanks to [#18423](https://github.com/storybookjs/storybook/pull/18243), which gives better control over hierarchical sorting.
|
||||
|
||||
In 6.x, the following configuration would sort any story/doc containing the title segment `Introduction` to the top of the sidebar, so this would match `Introduction`, `Example/Introduction`, `Very/Nested/Introduction`, etc.
|
||||
|
||||
```js
|
||||
// preview.js
|
||||
export default {
|
||||
parameters: {
|
||||
options: {
|
||||
storySort: {
|
||||
order: ['Introduction', '*'],
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
In 7.0+, the targeting is more precise, so the preceding example would match `Introduction`, but not anything nested. If you wanted to sort `Example/Introduction` first, you'd need to specify that:
|
||||
|
||||
```js
|
||||
storySort: {
|
||||
order: ['*', ['Introduction', '*']],
|
||||
}
|
||||
```
|
||||
|
||||
This would sort `*/Introduction` first, but not `Introduction` or `Very/Nested/Introduction`. If you want to target `Introduction` stories/docs anywhere in the hierarchy, you can do this with a [custom sort function](https://storybook.js.org/docs/react/writing-stories/naming-components-and-hierarchy#sorting-stories).
|
||||
|
||||
#### v7 Store API changes for addon authors
|
||||
|
||||
The Story Store in v7 mode is async, so synchronous story loading APIs no longer work. In particular:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user