diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 69973902038b..4da9b991daaf 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -37,12 +37,14 @@ "*.yaml", "*.md", "*.mdx", - "!docs/_snippets/**" + "!docs/**", + "docs/versions/**" ], "overrides": [ { - "files": ["docs/_snippets/**"], + "files": ["docs/**"], "options": { + "singleQuote": true, "trailingComma": "all" } }, diff --git a/docs/_snippets/button-story-with-addon-example.md b/docs/_snippets/button-story-with-addon-example.md index 40486d812154..e1d369e4faca 100644 --- a/docs/_snippets/button-story-with-addon-example.md +++ b/docs/_snippets/button-story-with-addon-example.md @@ -203,7 +203,7 @@ export const Basic: Story = { }); - + ``` ```js filename="Button.stories.js" renderer="svelte" language="js" tabTitle="CSF 3" @@ -248,7 +248,7 @@ export const Basic = {}; }); - + ``` ```ts filename="Button.stories.ts" renderer="svelte" language="ts" tabTitle="CSF 3" diff --git a/docs/_snippets/component-story-custom-args-complex.md b/docs/_snippets/component-story-custom-args-complex.md index 96f181e8a585..b2e6199e15e3 100644 --- a/docs/_snippets/component-story-custom-args-complex.md +++ b/docs/_snippets/component-story-custom-args-complex.md @@ -448,7 +448,7 @@ export const ExampleStory = { }; }, template: - '', + '', }; }, args: { @@ -499,7 +499,7 @@ export const ExampleStory: Story = { }; }, template: - '', + '', }; }, args: { @@ -720,7 +720,7 @@ export const ExampleStory = meta.story({ }; }, template: - '', + '', }; }, args: { @@ -770,7 +770,7 @@ export const ExampleStory = meta.story({ }; }, template: - '', + '', }; }, args: { diff --git a/docs/_snippets/component-story-static-asset-cdn.md b/docs/_snippets/component-story-static-asset-cdn.md index 6b753c1d8b9c..b07ef430b274 100644 --- a/docs/_snippets/component-story-static-asset-cdn.md +++ b/docs/_snippets/component-story-static-asset-cdn.md @@ -196,7 +196,7 @@ export default { export const WithAnImage = { render: () => ({ template: - 'My CDN placeholder', + 'My CDN placeholder', }), }; ``` @@ -216,7 +216,7 @@ type Story = StoryObj; export const WithAnImage: Story = { render: () => ({ template: - 'My CDN placeholder', + 'My CDN placeholder', }), }; ``` @@ -233,7 +233,7 @@ const meta = preview.meta({ export const WithAnImage = meta.story({ render: () => ({ template: - 'My CDN placeholder', + 'My CDN placeholder', }), }); ``` @@ -252,7 +252,7 @@ const meta = preview.meta({ export const WithAnImage = meta.story({ render: () => ({ template: - 'My CDN placeholder', + 'My CDN placeholder', }), }); ``` diff --git a/docs/_snippets/component-story-static-asset-with-import.md b/docs/_snippets/component-story-static-asset-with-import.md index 7db4cf01e027..3d3b4ca1e657 100644 --- a/docs/_snippets/component-story-static-asset-with-import.md +++ b/docs/_snippets/component-story-static-asset-with-import.md @@ -258,7 +258,7 @@ export const WithAnImage = { //👇 Returns the content of the image object created above. return { image }; }, - template: ``, + template: ``, }), }; ``` @@ -288,7 +288,7 @@ export const WithAnImage: Story = { //👇 Returns the content of the image object created above. return { image }; }, - template: ``, + template: ``, }), }; ``` @@ -315,7 +315,7 @@ export const WithAnImage = meta.story({ //👇 Returns the content of the image object created above. return { image }; }, - template: ``, + template: ``, }), }); ``` @@ -344,7 +344,7 @@ export const WithAnImage = meta.story({ //👇 Returns the content of the image object created above. return { image }; }, - template: ``, + template: ``, }), }); ``` diff --git a/docs/_snippets/custom-docs-page.md b/docs/_snippets/custom-docs-page.md index 32e344dfc44f..3227fe830987 100644 --- a/docs/_snippets/custom-docs-page.md +++ b/docs/_snippets/custom-docs-page.md @@ -61,15 +61,15 @@ If you didn't include the title in the story's default export, use this approach ### Primary - + ### Secondary - + ### Large - + ### Small diff --git a/docs/_snippets/list-story-reuse-data.md b/docs/_snippets/list-story-reuse-data.md index f462701e7e61..a0acd4c3a40f 100644 --- a/docs/_snippets/list-story-reuse-data.md +++ b/docs/_snippets/list-story-reuse-data.md @@ -304,9 +304,9 @@ export const ManyItems = { }, template: ` - - - + + + `, }), args: { @@ -340,9 +340,9 @@ export const ManyItems: Story = { }, template: ` - - - + + + `, }), args: { @@ -373,9 +373,9 @@ export const ManyItems = meta.story({ }, template: ` - - - + + + `, }), args: { @@ -408,9 +408,9 @@ export const ManyItems = meta.story({ }, template: ` - - - + + + `, }), args: { diff --git a/docs/_snippets/list-story-template.md b/docs/_snippets/list-story-template.md index 503fac6fd92b..b12d98463d73 100644 --- a/docs/_snippets/list-story-template.md +++ b/docs/_snippets/list-story-template.md @@ -370,7 +370,7 @@ const ListTemplate = { template: `
- +
`, @@ -417,7 +417,7 @@ export const ListTemplate: Story = { template: `
- +
`, @@ -460,7 +460,7 @@ export const Empty = meta.story({ template: `
- +
`, @@ -501,7 +501,7 @@ export const Empty = meta.story({ template: `
- +
`, diff --git a/docs/_snippets/list-story-unchecked.md b/docs/_snippets/list-story-unchecked.md index de9f24fed7ad..fa1e77b3f2b6 100644 --- a/docs/_snippets/list-story-unchecked.md +++ b/docs/_snippets/list-story-unchecked.md @@ -198,7 +198,7 @@ export const OneItem = { //👇 The args will now be passed down to the template return { args }; }, - template: '', + template: '', }), }; ``` @@ -231,7 +231,7 @@ export const OneItem: Story = { //👇 The args will now be passed down to the template return { args }; }, - template: '', + template: '', }), args: { ...Unchecked.args, @@ -264,7 +264,7 @@ export const OneItem = meta.story({ //👇 The args will now be passed down to the template return { args }; }, - template: '', + template: '', }), args: { ...Unchecked.input.args, @@ -299,7 +299,7 @@ export const OneItem = meta.story({ //👇 The args will now be passed down to the template return { args }; }, - template: '', + template: '', }), args: { ...Unchecked.input.args, diff --git a/docs/_snippets/my-component-story-basic-and-props.md b/docs/_snippets/my-component-story-basic-and-props.md index 38294f8af1c4..06d09ceee5c9 100644 --- a/docs/_snippets/my-component-story-basic-and-props.md +++ b/docs/_snippets/my-component-story-basic-and-props.md @@ -251,7 +251,7 @@ export const Basic = { export const WithProp = { render: () => ({ components: { MyComponent }, - template: '', + template: '', }), }; ``` @@ -278,7 +278,7 @@ export const Basic: Story = { export const WithProp: Story = { render: () => ({ components: { MyComponent }, - template: '', + template: '', }), }; ``` @@ -302,7 +302,7 @@ export const Basic = meta.story({ export const WithProp = meta.story({ render: () => ({ components: { MyComponent }, - template: '', + template: '', }), }); ``` @@ -326,7 +326,7 @@ export const Basic = meta.story({ export const WithProp = meta.story({ render: () => ({ components: { MyComponent }, - template: '', + template: '', }), }); ``` diff --git a/docs/addons/addon-knowledge-base.mdx b/docs/addons/addon-knowledge-base.mdx index 5dd7c2387d6e..fbe8767c0c84 100644 --- a/docs/addons/addon-knowledge-base.mdx +++ b/docs/addons/addon-knowledge-base.mdx @@ -13,20 +13,12 @@ It’s possible to disable the addon panel for a particular story. To make that possible, you need to pass the `paramKey` element when you register the panel: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Then when adding a story, you can pass a disabled parameter. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Style your addon Storybook uses [Emotion](https://emotion.sh/docs/introduction) for styling. Alongside with a theme that you can customize! @@ -38,41 +30,41 @@ If you don’t want to use Emotion, you can use inline styles or another css-in- Addon authors can develop their UIs using any React library. But we recommend using Storybook’s UI components in `storybook/internal/components` to build addons faster. When you use Storybook components, you get: -* Battle-tested off-the-shelf components -* Storybook native look and feel -* Built-in support for Storybook theming +- Battle-tested off-the-shelf components +- Storybook native look and feel +- Built-in support for Storybook theming Use the components listed below with your next addon. -| Component | Source | Story | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| Action Bar | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ActionBar/ActionBar.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-actionbar--single-item) | -| Addon Panel | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/addon-panel/addon-panel.tsx) | N/A | -| Badge | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Badge/Badge.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-badge--all-badges) | -| Button | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Button/Button.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-button--all-buttons) | -| Form | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/form/index.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-form-button--sizes) | -| Loader | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Loader/Loader.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-loader--progress-bar) | -| PlaceHolder | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/placeholder/placeholder.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-placeholder--single-child) | -| Scroll Area | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ScrollArea/ScrollArea.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-scrollarea--vertical) | -| Space | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/spaced/Spaced.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-spaced--row) | -| Syntax Highlighter | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/syntaxhighlighter/syntaxhighlighter.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-syntaxhighlighter--bash) | -| Tabs | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tabs/tabs.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tabs--stateful-static) | -| ToolBar | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/bar/bar.tsx) | N/A | -| ToolTip | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tooltip/Tooltip.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tooltip-tooltip--basic-default) | -| Zoom | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Zoom/Zoom.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-zoom--element-actual-size) | +| Component | Source | Story | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| Action Bar | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ActionBar/ActionBar.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-actionbar--single-item) | +| Addon Panel | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/addon-panel/addon-panel.tsx) | N/A | +| Badge | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Badge/Badge.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-badge--all-badges) | +| Button | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Button/Button.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-button--all-buttons) | +| Form | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/form/index.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-form-button--sizes) | +| Loader | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Loader/Loader.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-loader--progress-bar) | +| PlaceHolder | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/placeholder/placeholder.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-placeholder--single-child) | +| Scroll Area | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/ScrollArea/ScrollArea.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-scrollarea--vertical) | +| Space | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/spaced/Spaced.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-spaced--row) | +| Syntax Highlighter | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/syntaxhighlighter/syntaxhighlighter.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-syntaxhighlighter--bash) | +| Tabs | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tabs/tabs.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tabs--stateful-static) | +| ToolBar | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/bar/bar.tsx) | N/A | +| ToolTip | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/tooltip/Tooltip.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-tooltip-tooltip--basic-default) | +| Zoom | [See component implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/Zoom/Zoom.tsx) | [See component story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-zoom--element-actual-size) | Complementing the components, also included is a set of UI primitives. Use the content listed below as a reference for styling your addon. -| Component | Source | Story | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------| -------------------------------------------------------------------------------------------------------- | -| Color Palette (see note below) | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/addons/docs/src/blocks/components/ColorPalette.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-colorpalette--page) | -| Icon | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/icon/icon.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-icon--labels) | -| Typography | [See implementation](https://github.com/storybookjs/storybook/tree/next/code/core/src/components/components/typography) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-typography--all) | +| Component | Source | Story | +| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| Color Palette (see note below) | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/addons/docs/src/blocks/components/ColorPalette.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-colorpalette--page) | +| Icon | [See implementation](https://github.com/storybookjs/storybook/blob/next/code/core/src/components/components/icon/icon.tsx) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-icon--labels) | +| Typography | [See implementation](https://github.com/storybookjs/storybook/tree/next/code/core/src/components/components/typography) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-typography--all) | - The color palette implemented by `@storybook/addon-docs/blocks` is a high-level abstraction of the [`storybook/theming`](https://github.com/storybookjs/storybook/tree/next/code/core/src/theming) module. - +The color palette implemented by `@storybook/addon-docs/blocks` is a high-level abstraction of the [`storybook/theming`](https://github.com/storybookjs/storybook/tree/next/code/core/src/theming) module. + ## Build system @@ -88,7 +80,9 @@ When you're developing your addon as a package, you can’t use `npm link` to ad ``` - Run either `yarn` or `npm install` to install the addon. + +Run either `yarn` or `npm install` to install the addon. + ## Hot module replacement @@ -115,10 +109,6 @@ If you're developing a local Storybook addon built on top of an existing Storybo If you're working on a preset that loads third-party addons, which you don't have control over, and you need access to certain features (e.g., decorators) or provide additional configurations. In that case, you'll need to update your preset to the following to allow you to load and configure the other addons: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - If you have control over the addons you want to customize. In that case, you can update your preset and implement a custom function to load any additional presets and provide the necessary configuration. diff --git a/docs/addons/addon-migration-guide.mdx b/docs/addons/addon-migration-guide.mdx index ca15e5876ca3..a6abb969960f 100644 --- a/docs/addons/addon-migration-guide.mdx +++ b/docs/addons/addon-migration-guide.mdx @@ -8,7 +8,9 @@ sidebar: We sincerely appreciate the dedication and effort addon creators put into keeping the Storybook ecosystem vibrant and up-to-date. As Storybook evolves to version 10.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 9.x to 10.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the [Addon migration guide for Storybook 9.0](../../../release-9-1/docs/addons/addon-migration-guide.mdx). - We also have a general [Storybook migration guide](../releases/migration-guide.mdx) that covers updates to your Storybook instance rather than your addon code. + +We also have a general [Storybook migration guide](../releases/migration-guide.mdx) that covers updates to your Storybook instance rather than your addon code. + ## Dependency updates @@ -20,11 +22,11 @@ You will need to update your Storybook dependencies. Peer dependencies must poin "devDependencies": { "@storybook/addon-docs": "next", "@storybook/react-vite": "next", - "storybook": "next" + "storybook": "next", }, "peerDependencies": { - "storybook": "^10.0.0" - } + "storybook": "^10.0.0", + }, } ``` @@ -38,15 +40,16 @@ If your addon supports multiple major versions of Storybook, you can specify a w { "name": "your-storybook-addon", "peerDependencies": { - "storybook": "^9.0.0 || ^10.0.0" + "storybook": "^9.0.0 || ^10.0.0", }, "devDependencies": { - "storybook": ">=10.0.0-0 <11.0.0-0" // For local development - } + "storybook": ">=10.0.0-0 <11.0.0-0", // For local development + }, } ``` However, we recommend releasing a new major version of your addon alongside new major versions of Storybook. This practice: + 1. Makes it easier to maintain your code 2. Allows you to take advantage of new features and improvements 3. Provides a clearer upgrade path for your users @@ -60,11 +63,12 @@ Here are the changes in version 10.0 that impact addon development. Storybook 10 requires all addons to be built as ESM-only. This change simplifies the build process and reduces maintenance overhead. You'll need to make many changes to `tsup.config.ts`, so it can be easier to copy the reference file in the [`addon-kit` repository](https://github.com/storybookjs/addon-kit/blob/main/tsup.config.ts). This update brings the following changes: -* The Node target moves from Node 20.0 to Node 20.19 -* You no longer need to build CJS files -* You no longer need to pass `globalManagerPackages` and `globalPreviewPackages` -* The `bundler` config in `package.json` no longer needs to be manually typed -* We recommend you stop using `exportEntries` and switch exported entries to `previewEntries` and `managerEntries` instead based on where they are consumed by your users + +- The Node target moves from Node 20.0 to Node 20.19 +- You no longer need to build CJS files +- You no longer need to pass `globalManagerPackages` and `globalPreviewPackages` +- The `bundler` config in `package.json` no longer needs to be manually typed +- We recommend you stop using `exportEntries` and switch exported entries to `previewEntries` and `managerEntries` instead based on where they are consumed by your users ```diff title="tsup.config.ts" - import { readFile } from "node:fs/promises"; @@ -259,21 +263,20 @@ Finally, change the `preset.js` file at the top-level of your addon to be ESM. T Because addons are now ESM-only, you must change how you load your own addon in your development Storybook instance. Imports and exports must now follow ESM syntax, and relative paths must use `import.meta.resolve`. - Remove `.storybook/local-preset.cjs` and create `.storybook/local-preset.ts` with the following content: ```ts title=".storybook/local-preset.ts" -import { fileURLToPath } from "node:url"; +import { fileURLToPath } from 'node:url'; export function previewAnnotations(entry = []) { - return [...entry, fileURLToPath(import.meta.resolve("../dist/preview.js"))]; + return [...entry, fileURLToPath(import.meta.resolve('../dist/preview.js'))]; } export function managerEntries(entry = []) { - return [...entry, fileURLToPath(import.meta.resolve("../dist/manager.js"))]; + return [...entry, fileURLToPath(import.meta.resolve('../dist/manager.js'))]; } -export * from "../dist/preset.js"; +export * from '../dist/preset.js'; ``` Next, update your `main.ts` to reference the new preset file: @@ -288,6 +291,7 @@ Next, update your `main.ts` to reference the new preset file: The following changes are not strictly required yet, but we recommend making them to improve your users' experience. ### CSF Factories support + To support CSF Factories annotations in your addon, you will need to update your `src/index.ts` file to use the new `definePreviewAddon`. This feature will be part of [CSF Next](../api/csf/csf-next.mdx). This change is highly recommended, as it will help your own users reap the benefits of CSF Factories. With CSF Factories, users can chain their preview configuration and benefit from better typing and more flexibility. Addons must export annotations to be compatible with this new syntax. CSF Factories will be the default way to write stories in Storybook 11. diff --git a/docs/addons/addon-types.mdx b/docs/addons/addon-types.mdx index f8d5b48f3a3e..b81d6864b7d6 100644 --- a/docs/addons/addon-types.mdx +++ b/docs/addons/addon-types.mdx @@ -1,8 +1,7 @@ --- -title: 'Types of addons' +title: Types of addons sidebar: order: 6 - title: Types of addons --- Each Storybook addon is classified into two general categories, UI-based or Presets. Each type of addons feature is documented here. Use this as a reference when creating your addon. @@ -19,12 +18,8 @@ Panel addons allow you to add your own UI in Storybook's addon panel. This is th Use this boilerplate code to add a new `Panel` to Storybook's UI: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### Toolbars Toolbar addons allow you to add your own custom tools in Storybook's Toolbar. For example, the official [`@storybook/addon-themes`](https://storybook.js.org/addons/@storybook/addon-themes) uses this pattern. @@ -33,14 +28,12 @@ Toolbar addons allow you to add your own custom tools in Storybook's Toolbar. Fo Use this boilerplate code to add a new `button` to Storybook's Toolbar: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - The `match` property allows you to conditionally render your toolbar addon, [based on the current view](./writing-addons.mdx#conditionally-render-the-addon). The `icon` element used in the example loads the icons from the `storybook/internal/components` module. See [here](../faq.mdx#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. + +The `match` property allows you to conditionally render your toolbar addon, [based on the current view](./writing-addons.mdx#conditionally-render-the-addon). The `icon` element used in the example loads the icons from the `storybook/internal/components` module. See [here](../faq.mdx#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. + ### Tabs @@ -51,14 +44,12 @@ Tab addons allow you to create your own custom tabs in Storybook. Use this boilerplate code to add a new `Tab` to Storybook's UI: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - Learn how to write your own addon that includes these UI elements [here](./writing-addons.mdx). + +Learn how to write your own addon that includes these UI elements [here](./writing-addons.mdx). + ## Preset addons @@ -67,16 +58,12 @@ Storybook preset addons are grouped collections of `babel`, `webpack`, and `addo Use this boilerplate code while writing your own preset addon. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - **Learn more about the Storybook addon ecosystem** -* Types of addons for other types of addons -* [Writing addons](./writing-addons.mdx) for the basics of addon development -* [Presets](./writing-presets.mdx) for preset development -* [Integration catalog](./integration-catalog.mdx) for requirements and available recipes -* [API reference](./addons-api.mdx) to learn about the available APIs +- Types of addons for other types of addons +- [Writing addons](./writing-addons.mdx) for the basics of addon development +- [Presets](./writing-presets.mdx) for preset development +- [Integration catalog](./integration-catalog.mdx) for requirements and available recipes +- [API reference](./addons-api.mdx) to learn about the available APIs diff --git a/docs/addons/addons-api.mdx b/docs/addons/addons-api.mdx index d2b518e44adb..454123eea161 100644 --- a/docs/addons/addons-api.mdx +++ b/docs/addons/addons-api.mdx @@ -1,8 +1,7 @@ --- -title: 'Addon API' +title: Addon API sidebar: order: 8 - title: Addon API --- Storybook's API allows developers to interact programmatically with Storybook. With the API, developers can build and deploy custom addons and other tools that enhance Storybook's functionality. @@ -11,43 +10,33 @@ Storybook's API allows developers to interact programmatically with Storybook. W Our API is exposed via two distinct packages, each one with a different purpose: -* `storybook/manager-api` used to interact with the Storybook manager UI or access the Storybook API. -* `storybook/preview-api` used to control and configure the addon's behavior. - -{/* prettier-ignore-start */} +- `storybook/manager-api` used to interact with the Storybook manager UI or access the Storybook API. +- `storybook/preview-api` used to control and configure the addon's behavior. -{/* prettier-ignore-end */} - ### addons.add() The `add` method allows you to register the type of UI component associated with the addon (e.g., panels, toolbars, tabs). For a minimum viable Storybook addon, you should provide the following arguments: -* `type`: The type of UI component to register. -* `title`: The title to feature in the Addon Panel. -* `render`: The function that renders the addon's UI component. - -{/* prettier-ignore-start */} +- `type`: The type of UI component to register. +- `title`: The title to feature in the Addon Panel. +- `render`: The function that renders the addon's UI component. -{/* prettier-ignore-end */} - - The render function is called with `active`. The `active` value will be true when the panel is focused on the UI. + +The render function is called with `active`. The `active` value will be true when the panel is focused on the UI. + ### addons.register() Serves as the entry point for all addons. It allows you to register an addon and access the Storybook [API](#storybook-api). For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Now you'll get an instance to our StorybookAPI. See the [api docs](#storybook-api) for Storybook API regarding using that. ### addons.getChannel() @@ -56,34 +45,28 @@ Get an instance to the channel to communicate with the manager and the preview. It has a NodeJS [EventEmitter](https://nodejs.org/api/events.html) compatible API. So, you can use it to emit events and listen to events. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### makeDecorator Use the `makeDecorator` API to create decorators in the style of the official addons. Like so: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - If the story's parameters include `{ exampleParameter: { disable: true } }` (where `exampleParameter` is the `parameterName` of your addon), your decorator will not be called. + +If the story's parameters include `{ exampleParameter: { disable: true } }` (where `exampleParameter` is the `parameterName` of your addon), your decorator will not be called. + The `makeDecorator` API requires the following arguments: -* `name`: Unique name to identify the custom addon decorator. -* `parameterName`: Sets a unique parameter to be consumed by the addon. -* `skipIfNoParametersOrOptions`: (Optional) Doesn't run the decorator if the user hasn't options either via [decorators](../writing-stories/decorators.mdx) or [parameters](../writing-stories/parameters.mdx). -* `wrapper`: your decorator function. Takes the `getStory`, `context`, and both the `options` and `parameters` (as defined in `skipIfNoParametersOrOptions` above). +- `name`: Unique name to identify the custom addon decorator. +- `parameterName`: Sets a unique parameter to be consumed by the addon. +- `skipIfNoParametersOrOptions`: (Optional) Doesn't run the decorator if the user hasn't options either via [decorators](../writing-stories/decorators.mdx) or [parameters](../writing-stories/parameters.mdx). +- `wrapper`: your decorator function. Takes the `getStory`, `context`, and both the `options` and `parameters` (as defined in `skipIfNoParametersOrOptions` above). -*** +--- ## Storybook API @@ -93,68 +76,40 @@ Storybook's API allows you to access different functionalities of Storybook UI. The `selectStory` API method allows you to select a single story. It accepts the following two parameters; story kind name and an optional story name. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - This is how you can select the above story: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.selectInCurrentKind() Similar to the `selectStory` API method, but it only accepts the story as the only parameter. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.setQueryParams() This method allows you to set query string parameters. You can use that as temporary storage for addons. Here's how you define query params: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Additionally, if you need to remove a query parameter, set it as `null` instead of removing them from the addon. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.getQueryParam() Allows retrieval of a query parameter enabled via the `setQueryParams` API method. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.getUrlState(overrideParams) This method allows you to get the application URL state, including any overridden or custom parameter values. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.getStoryHrefs(storyId, options?) Get the manager and preview URLs for a story. URLs are relative to the current Storybook, unless `base` is set, or in case of previewHref with `refId` set. @@ -168,22 +123,14 @@ Get the manager and preview URLs for a story. URLs are relative to the current S - `refId`: ID of the ref to get the URL for (for composed Storybooks) - `viewMode`: The view mode to use, defaults to 'story'. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.on(eventName, fn) This method allows you to register a handler function called whenever the user navigates between stories. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.openInEditor(payload) Opens a file in the configured code editor. Useful for "Edit in IDE" functionality in addons. @@ -194,77 +141,53 @@ Opens a file in the configured code editor. Useful for "Edit in IDE" functionali Returns a Promise that resolves with information about whether the operation was successful. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.getCurrentStoryData() Returns the current story's data, including its ID, kind, name, and parameters. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.toggleFullscreen(toggled?) Toggles the fullscreen mode of the Storybook UI. Pass `true` to enable fullscreen, `false` to disable, or omit to toggle the current state. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.togglePanel(toggled?) Toggles the visibility of the addon panel. Pass `true` to show the panel, `false` to hide, or omit to toggle the current state. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### api.addNotification(notification) Displays a notification in the Storybook UI. The notification object should contain `id`, `content`, and optionally `duration` and `icon`. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### addons.setConfig(config) This method allows you to override the default Storybook UI configuration (e.g., set up a [theme](../configure/user-interface/theming.mdx) or hide UI elements): -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - The following table details how to use the API values: -| Name | Type | Description | Example Value | -| --------------------- | --------------- | ------------------------------------------------------- | ------------------------------------- | -| **navSize** | Number (pixels) | The size of the sidebar that shows a list of stories | `300` | -| **bottomPanelHeight** | Number (pixels) | The size of the addon panel when in the bottom position | `200` | -| **rightPanelWidth** | Number (pixels) | The size of the addon panel when in the right position | `200` | -| **panelPosition** | String | Where to show the addon panel | `'bottom'` or `'right'` | -| **enableShortcuts** | Boolean | Enable/disable shortcuts | `true` | -| **showToolbar** | Boolean | Show/hide toolbar | `true` | -| **theme** | Object | Storybook Theme, see next section | `undefined` | -| **selectedPanel** | String | Id to select an addon panel | `storybook/actions/panel` | -| **initialActive** | String | Select the default active tab on Mobile | `sidebar` or `canvas` or `addons` | -| **sidebar** | Object | Sidebar options, see below | `{ showRoots: false }` | -| **toolbar** | Object | Modify the tools in the toolbar using the addon id | `{ fullscreen: { hidden: false } }` | +| Name | Type | Description | Example Value | +| --------------------- | --------------- | ------------------------------------------------------- | ----------------------------------- | +| **navSize** | Number (pixels) | The size of the sidebar that shows a list of stories | `300` | +| **bottomPanelHeight** | Number (pixels) | The size of the addon panel when in the bottom position | `200` | +| **rightPanelWidth** | Number (pixels) | The size of the addon panel when in the right position | `200` | +| **panelPosition** | String | Where to show the addon panel | `'bottom'` or `'right'` | +| **enableShortcuts** | Boolean | Enable/disable shortcuts | `true` | +| **showToolbar** | Boolean | Show/hide toolbar | `true` | +| **theme** | Object | Storybook Theme, see next section | `undefined` | +| **selectedPanel** | String | Id to select an addon panel | `storybook/actions/panel` | +| **initialActive** | String | Select the default active tab on Mobile | `sidebar` or `canvas` or `addons` | +| **sidebar** | Object | Sidebar options, see below | `{ showRoots: false }` | +| **toolbar** | Object | Modify the tools in the toolbar using the addon id | `{ fullscreen: { hidden: false } }` | The following options are configurable under the `sidebar` namespace: @@ -276,11 +199,11 @@ The following options are configurable under the `sidebar` namespace: The following options are configurable under the `toolbar` namespace: -| Name | Type | Description | Example Value | -| --------- | ------ | -------------------------------------------------------------------- | ------------------- | -| **[id]** | String | Toggle visibility for a specific toolbar item (e.g. `title`, `zoom`) | `{ hidden: false }` | +| Name | Type | Description | Example Value | +| -------- | ------ | -------------------------------------------------------------------- | ------------------- | +| **[id]** | String | Toggle visibility for a specific toolbar item (e.g. `title`, `zoom`) | `{ hidden: false }` | -*** +--- ## Storybook hooks @@ -290,78 +213,50 @@ To help streamline addon development and reduce boilerplate code, the API expose It allows access to Storybook's internal state. Similar to the [`useglobals`](#useglobals) hook, we recommend optimizing your addon to rely on [`React.memo`](https://react.dev/reference/react/memo), or the following hooks; [`useMemo`](https://react.dev/reference/react/useMemo), [`useCallback`](https://react.dev/reference/react/useCallback) to prevent a high volume of re-render cycles. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useStorybookApi The `useStorybookApi` hook is a convenient helper to allow you full access to the [Storybook API](#storybook-api) methods. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useChannel Allows setting subscriptions to events and getting the emitter to emit custom events to the channel. The messages can be listened to on both the iframe and the manager. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useAddonState The `useAddonState` is a useful hook for addons that require data persistence, either due to Storybook's UI lifecycle or for more complex addons involving multiple types (e.g., toolbars, panels). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useParameter The `useParameter` retrieves the current story's parameters. If the parameter's value is not defined, it will automatically default to the second value defined. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useGlobals Extremely useful hook for addons that rely on Storybook [Globals](../essentials/toolbars-and-globals.mdx). It allows you to obtain and update `global` values. We also recommend optimizing your addon to rely on [`React.memo`](https://react.dev/reference/react/memo), or the following hooks; [`useMemo`](https://react.dev/reference/react/useMemo), [`useCallback`](https://react.dev/reference/react/useCallback) to prevent a high volume of re-render cycles. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### useArgs Hook that allows you to retrieve or update a story's [`args`](../writing-stories/args.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - **Learn more about the Storybook addon ecosystem** -* [Types of addons](./addon-types.mdx) for other types of addons -* [Writing addons](./writing-addons.mdx) for the basics of addon development -* [Presets](./writing-presets.mdx) for preset development -* [Integration catalog](./integration-catalog.mdx) for requirements and available recipes -* API reference to learn about the available APIs +- [Types of addons](./addon-types.mdx) for other types of addons +- [Writing addons](./writing-addons.mdx) for the basics of addon development +- [Presets](./writing-presets.mdx) for preset development +- [Integration catalog](./integration-catalog.mdx) for requirements and available recipes +- API reference to learn about the available APIs diff --git a/docs/addons/configure-addons.mdx b/docs/addons/configure-addons.mdx index 72e4d73d5c1f..af651eee284b 100644 --- a/docs/addons/configure-addons.mdx +++ b/docs/addons/configure-addons.mdx @@ -1,5 +1,5 @@ --- -title: 'Configure and communicate with an addon' +title: Configure and communicate with an addon sidebar: order: 3 title: Configure addons @@ -11,7 +11,7 @@ The addon API is designed for customization. It offers addon authors different w Presets offload the burden of configuration from the user to the addon. Preset options are global and are accessible from NodeJS. They're ideal for pre-configuring Webpack loaders, Babel plugins, and other library or framework-specific configurations. -For example, many libraries require that the app be wrapped by a `Provider` which *provides* data to components down the tree. Presets can describe behavior like adding wrappers automatically, without users having to do any manual configuration. If a user installs an addon that has Presets, the addon can instruct Storybook to wrap all stories in `Provider`. This allows folks to start using your library with Storybook, with just 1 line of config! +For example, many libraries require that the app be wrapped by a `Provider` which _provides_ data to components down the tree. Presets can describe behavior like adding wrappers automatically, without users having to do any manual configuration. If a user installs an addon that has Presets, the addon can instruct Storybook to wrap all stories in `Provider`. This allows folks to start using your library with Storybook with a single line of config. For more on presets, see: [Write a preset addon](./writing-presets.mdx) diff --git a/docs/addons/index.mdx b/docs/addons/index.mdx index f164e16f0746..f92656eb489a 100644 --- a/docs/addons/index.mdx +++ b/docs/addons/index.mdx @@ -1,5 +1,5 @@ --- -title: 'Introduction to addons' +title: Introduction to addons hideRendererSelector: true sidebar: order: 9 @@ -17,10 +17,10 @@ Before writing your first [addon](https://storybook.js.org/addons), let’s take The **Manager** is the UI responsible for rendering the: -* 🔍 Search -* 🧭 Navigation -* 🔗 Toolbars -* 📦 Addons +- 🔍 Search +- 🧭 Navigation +- 🔗 Toolbars +- 📦 Addons The **Preview** area is an `iframe` where your stories are rendered. diff --git a/docs/addons/install-addons.mdx b/docs/addons/install-addons.mdx index c4e8f66defcf..2abbc89fdf28 100644 --- a/docs/addons/install-addons.mdx +++ b/docs/addons/install-addons.mdx @@ -1,5 +1,5 @@ --- -title: 'Install addons' +title: Install addons sidebar: order: 1 title: Install @@ -13,14 +13,12 @@ Storybook includes a [`storybook add`](../api/cli-options.mdx#add) command to au Run the `storybook add` command using your chosen package manager, and the CLI will update your Storybook configuration to include the addon and install any necessary dependencies. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - If you're attempting to install multiple addons at once, it will only install the first addon that was specified. This is a known limitation of the current implementation and will be addressed in a future release. + +If you're attempting to install multiple addons at once, it will only install the first addon that was specified. This is a known limitation of the current implementation and will be addressed in a future release. + ### Manual installation @@ -29,20 +27,12 @@ Storybook addons are always added through the [`addons`](../api/main-config/main Run the following command with your package manager of choice to install the addon. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Next, update `.storybook/main.js|ts` to the following: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - When you run Storybook, the accessibility testing addon will be enabled. ![Storybook addon installed and registered](../_assets/addons/storybook-addon-installed-registered.png) @@ -51,8 +41,4 @@ When you run Storybook, the accessibility testing addon will be enabled. To remove an addon from Storybook, you can choose to manually uninstall it and remove it from the configuration file (i.e., [`.storybook/main.js|ts`](../configure/index.mdx)) or opt-in to do it automatically via the CLI with the [`remove`](../api/cli-options.mdx#remove) command. For example, to remove the [Accessibility addon](https://storybook.js.org/addons/@storybook/addon-a11y) from Storybook with the CLI, run the following command: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/addons/integration-catalog.mdx b/docs/addons/integration-catalog.mdx index e92266353666..ba3a172ed2f6 100644 --- a/docs/addons/integration-catalog.mdx +++ b/docs/addons/integration-catalog.mdx @@ -1,5 +1,5 @@ --- -title: 'Add to the integration catalog' +title: Add to the integration catalog sidebar: order: 5 title: Add to catalog @@ -13,13 +13,15 @@ Storybook addons are distributed via npm. The catalog is populated by querying n Add your addon to the catalog by publishing a npm package that follows these requirements: -* `package.json` with [module information](./writing-addons.mdx#setup) and [addon metadata](#addon-metadata) -* `README.md` file with installation and configuration instructions -* `/dist` directory containing transpiled ES5 code -* `preset.js` file written as an ES5 module at the root level +- `package.json` with [module information](./writing-addons.mdx#setup) and [addon metadata](#addon-metadata) +- `README.md` file with installation and configuration instructions +- `/dist` directory containing transpiled ES5 code +- `preset.js` file written as an ES5 module at the root level - Get a refresher on how to [write a Storybook addon](./writing-addons.mdx). + +Get a refresher on how to [write a Storybook addon](./writing-addons.mdx). + ### Addon metadata @@ -31,32 +33,34 @@ We rely on metadata to organize your addon in the catalog. You must add the - Make sure to copy each item **exactly** as listed so that we can properly index your addon in our catalog. + +Make sure to copy each item **exactly** as listed so that we can properly index your addon in our catalog. + ```json title="package.json" @@ -103,8 +107,8 @@ If you'd like to request a recipe, open a [new discussion](https://github.com/st **Learn more about the Storybook addon ecosystem** -* [Types of addons](./addon-types.mdx) for other types of addons -* [Writing addons](./writing-addons.mdx) for the basics of addon development -* [Presets](./writing-presets.mdx) for preset development -* Integration catalog for requirements and available recipes -* [API reference](./addons-api.mdx) to learn about the available APIs +- [Types of addons](./addon-types.mdx) for other types of addons +- [Writing addons](./writing-addons.mdx) for the basics of addon development +- [Presets](./writing-presets.mdx) for preset development +- Integration catalog for requirements and available recipes +- [API reference](./addons-api.mdx) to learn about the available APIs diff --git a/docs/addons/writing-addons.mdx b/docs/addons/writing-addons.mdx index 9fe4f23b0e4f..7f0ee73b8d48 100644 --- a/docs/addons/writing-addons.mdx +++ b/docs/addons/writing-addons.mdx @@ -1,5 +1,5 @@ --- -title: 'Write an addon' +title: Write an addon sidebar: order: 2 title: Write @@ -24,14 +24,12 @@ There are two main categories of addons, each with its role: The addon built in this guide is a UI-based addon, specifically a [toolbar](./addon-types.mdx#toolbars) addon, enabling users to draw outlines around each element in the story through a shortcut or click of a button. UI addons can create other types of UI elements, each with its function: [panels](./addon-types.mdx#panels) and [tabs](./addon-types.mdx#tabs), providing users with various ways to interact with the UI. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - + Addons with a UI must use the same React version as Storybook. If your component library uses a different React version, you must use addons that are built and published as standalone packages. We'll cover how to do this with the [Addon Kit](https://github.com/storybookjs/addon-kit). + ## Setup @@ -42,15 +40,13 @@ To create your first addon, you're going to use the [Addon Kit](https://github.c Clone the repository you just created and install its dependencies. When the installation process finishes, you will be prompted with questions to configure your addon. Answer them, and when you're ready to start building your addon, run the following command to start Storybook in development mode and develop your addon in watch mode: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - The Addon Kit uses [Typescript](https://www.typescriptlang.org/) by default. If you want to use - JavaScript instead, you can run the `eject-ts` command to convert the project to JavaScript. + +The Addon Kit uses [Typescript](https://www.typescriptlang.org/) by default. If you want to use +JavaScript instead, you can run the `eject-ts` command to convert the project to JavaScript. + ### Understanding the build system @@ -65,12 +61,8 @@ The `tsup` configuration handles these complexities by default, but you can cust By default, code for the UI-based addons is located in one of the following files, depending on the type of addon built: **`src/Tool.tsx`**, **`src/Panel.tsx`**, or **`src/Tab.tsx`**. Since we're building a toolbar addon, we can safely remove the `Panel` and `Tab` files and update the remaining file to the following: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Going through the code blocks in sequence: ```ts title="src/Tool.tsx" @@ -125,12 +117,8 @@ The `Tool` component is the entry point of the addon. It renders the UI elements Moving onto the manager, here we register the addon with Storybook using a unique name and identifier. Since we've removed the `Panel` and `Tab` files, we'll need to adjust the file to only reference the addon we're building. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### Conditionally render the addon Notice the `match` property. It allows you to control the view mode (story or docs) and tab (the story canvas or [custom tabs](./addon-types.mdx#tabs)) where the toolbar addon is visible. For example: @@ -148,28 +136,16 @@ Run the `start` script to build and start Storybook and verify that the addon is In Storybook, applying styles for addons is considered a side-effect. Therefore, we'll need to make some changes to our addon to allow it to use the styles when it is active and remove them when it's disabled. We're going to rely on two of Storybook's features to handle this: [decorators](../writing-stories/decorators.mdx) and [globals](../essentials/toolbars-and-globals.mdx#globals). To handle the CSS logic, we must include some helper functions to inject and remove the stylesheets from the DOM. Start by creating the helper file with the following content: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Next, create the file with the styles we want to inject with the following content: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Since the addon can be active in both the story and documentation modes, the DOM node for Storybook's preview `iframe` is different in these two modes. In fact, Storybook renders multiple story previews on one page when in documentation mode. Therefore, we'll need to choose the correct selector for the DOM node where the styles will be injected and ensure the CSS is scoped to that particular selector. That mechanism is provided as an example within the `src/withGlobals.ts` file, which we'll use to connect the styling and helper functions to the addon logic. Update the file to the following: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Packaging and publishing Storybook addons, similar to most packages in the JavaScript ecosystem, are distributed as NPM packages. However, they have specific criteria that need to be met to be published to NPM and crawled by the integration catalog: @@ -232,9 +208,11 @@ The second metadata category is related to the [integration catalog](https://sto ``` - The `storybook` configuration element includes additional properties that help customize the - addon's searchability and indexing. For more information, see the [Integration catalog - documentation](./integration-catalog.mdx). + +The `storybook` configuration element includes additional properties that help customize the +addon's searchability and indexing. For more information, see the [Integration catalog +documentation](./integration-catalog.mdx). + One essential item to note is the `keywords` property as it maps to the catalog's tag system. Adding the `storybook-addon` keyword ensures that the addon is discoverable in the catalog when searching for addons. The remaining keywords help with the searchability and categorization of the addon. @@ -261,12 +239,8 @@ npx auto create-labels Finally, run the following command to create a release for your addon. This will build and package the addon code, bump the version, push the release into GitHub and npm, and generate a changelog. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### CI automation By default, the Addon Kit comes pre-configured with a GitHub Actions workflow, enabling you to automate the release management process. This ensures that the package is always up to date with the latest changes and that the changelog is updated accordingly. However, you'll need additional configuration to use your NPM and GitHub tokens to publish the package successfully. In your repository, click the **Settings** tab, then the **Secrets and variables** dropdown, followed by the **Actions** item. You should see the following screen: diff --git a/docs/addons/writing-presets.mdx b/docs/addons/writing-presets.mdx index 9c9896a0ab7d..2c91b1f74b32 100644 --- a/docs/addons/writing-presets.mdx +++ b/docs/addons/writing-presets.mdx @@ -1,5 +1,5 @@ --- -title: 'Write a preset addon' +title: Write a preset addon sidebar: order: 4 title: Write a preset @@ -15,22 +15,14 @@ Preset addons allow developers to compose various configuration options and plug This type of preset allows you to encapsulate and organize configurations specific to the addon, including [builder](../builders/index.mdx) support, [Babel](https://babeljs.io/), or third-party integrations. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### Root-level presets This type of preset is user-facing and responsible for registering the addon without any additional configuration from the user by bundling Storybook-related features (e.g., [parameters](../writing-stories/parameters.mdx)) via the [`previewAnnotations`](../api/main-config/main-config-preview-annotations.mdx) and UI related features (e.g., addons) via the `managerEntries` API. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Presets API When writing a preset, you can access a select set of APIs to interact with the Storybook environment, including the supported builders (e.g., Webpack, Vite), the Storybook configuration, and UI. Below are the available APIs you can use when writing a preset addon. @@ -39,14 +31,12 @@ When writing a preset, you can access a select set of APIs to interact with the To customize Storybook's Babel configuration and add support for additional features, you can use the [`babelDefault`](../api/main-config/main-config-babel-default.mdx) API. It will apply the provided configuration ahead of any other user presets, which can be further customized by the end user via the [`babel`](../api/main-config/main-config-babel.mdx) configuration option. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - The Babel configuration is only applied to frameworks that use Babel internally. If you enable it for a framework that uses a different compiler, like [SWC](https://swc.rs/) or [esbuild](https://esbuild.github.io/), it will be ignored. + +The Babel configuration is only applied to frameworks that use Babel internally. If you enable it for a framework that uses a different compiler, like [SWC](https://swc.rs/) or [esbuild](https://esbuild.github.io/), it will be ignored. + ### Builders @@ -57,62 +47,38 @@ By default, Storybook provides support for the leading industry builders, includ If you are creating a preset and want to include Vite support, the `viteFinal` API can be used to modify the default configuration and enable additional features. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - #### Webpack To customize the Webpack configuration in Storybook to add support for additional file types, apply specific loaders, configure plugins, or make any other necessary modifications, you can use the `webpackFinal` API. Once invoked, it will extend the default Webpack configuration with the provided configuration. An example of this would be: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### ManagerEntries If you're writing a preset that loads third-party addons, which you may not have control over, but require access to specific features or additional configuration, you can use the `managerEntries` API. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### PreviewAnnotations If you need additional settings to render stories for a preset, like [decorators](../writing-stories/decorators.mdx) or [parameters](../writing-stories/parameters.mdx), you can use the `previewAnnotations` API. For example, to apply a decorator to all stories, create a preview file that includes the decorator and make it available to the preset as follows: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Advanced configuration The presets API is designed to be flexible and allow you to customize Storybook to your specific needs, including using presets for more advanced use cases without publishing them. In such cases, you can rely on a private preset. These private presets contain configuration options meant for development purposes and not for end-users. The `.storybook/main.js|ts` file is an example of such a private preset that empowers you to modify the behavior and functionality of Storybook. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### Addons For addon consumers, the [`managerEntries`](#managerentries) API can be too technical, making it difficult to use. To make it easier to add addons to Storybook, the preset API provides the [`addons`](../api/main-config/main-config-addons.mdx) API, which accepts an array of addon names and will automatically load them for you. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - The array of values supports references to additional presets and addons that should be included in the manager. Storybook will automatically detect whether the provided value is a preset or an addon and load it accordingly. ### Entries @@ -123,20 +89,12 @@ Entries are the place to register entry points for the preview. This feature can The Storybook preset API also provides access to the UI configuration, including the `head` and `body` HTML elements of the preview, configured by the [`previewHead`](../api/main-config/main-config-preview-head.mdx) and [`previewBody`](../api/main-config/main-config-preview-body.mdx) APIs. Both allow you to set up Storybook in a way that is similar to using the [`preview-head.html`](../configure/story-rendering.mdx#adding-to-head) and [`preview-body.html`](../configure/story-rendering.mdx#adding-to-body) files. These methods accept a string and return a modified version, injecting the provided content into the HTML element. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Additionally, if you need to customize the manager (i.e., where Storybook’s search, navigation, toolbars, and addons render), you can use the [`managerHead`](../api/main-config/main-config-manager-head.mdx) to modify the UI, similar to how you would do it with the `manager-head.html` file. For example: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - However, if you need, you can also customize the template used by Storybook to render the UI. To do so, you can use the `previewMainTemplate` API and provide a reference for a custom template created as a `ejs` file. For an example of how to do this, see the [template](https://github.com/storybookjs/storybook/blob/next/code/builders/builder-webpack5/templates/preview.ejs) used by the Webpack 5 builder. ## Troubleshooting @@ -147,8 +105,8 @@ As Storybook relies on [esbuild](https://esbuild.github.io/) instead of Webpack **Learn more about the Storybook addon ecosystem** -* [Types of addons](./addon-types.mdx) for other types of addons -* [Writing addons](./writing-addons.mdx) for the basics of addon development -* Presets for preset development -* [Integration catalog](./integration-catalog.mdx) for requirements and available recipes -* [API reference](./addons-api.mdx) to learn about the available APIs +- [Types of addons](./addon-types.mdx) for other types of addons +- [Writing addons](./writing-addons.mdx) for the basics of addon development +- Presets for preset development +- [Integration catalog](./integration-catalog.mdx) for requirements and available recipes +- [API reference](./addons-api.mdx) to learn about the available APIs diff --git a/docs/ai/best-practices.mdx b/docs/ai/best-practices.mdx index 3143c2d8c303..efa101fa403e 100644 --- a/docs/ai/best-practices.mdx +++ b/docs/ai/best-practices.mdx @@ -4,11 +4,13 @@ sidebar: order: 2 title: Best practices --- - + - The best practices here relate to the [generated manifests](./manifests.mdx), which are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +The best practices here relate to the [generated manifests](./manifests.mdx), which are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + @@ -74,17 +76,20 @@ export interface ButtonProps { For unattached MDX docs pages (such as documentation for design tokens, guidelines, etc.), you can provide a summary in the `Meta` tag, which will be included in the manifest and provided to the agent. -```jsx title="Colors.mdx" +```mdx title="Colors.mdx" import { Meta } from '@storybook/addon-docs/blocks'; - + ``` ## Docs content Storybook generates this docs manifest through static analysis of your MDX files, which means it is limited to the information that is explicitly present in those files. For example, the manifest will _not_ include the color tokens in the document below, because their values are not explicitly in the source: -```jsx title="Colors.mdx" +```mdx title="Colors.mdx" import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks'; import { colors } from '../src/tokens/colors'; @@ -93,6 +98,7 @@ import { colors } from '../src/tokens/colors'; # Colors {/* 👇 These colors are *not* included in the manifest, because their values are not explicitly in the source */} + {colors.map((color) => ( @@ -116,7 +122,7 @@ You can also remove an entire component from the manifest, by removing the tag i Similarly, to exclude an entire MDX docs page from the manifests, you can remove the `manifest` tag from the page's metadata: -```jsx title="DocForHumansOnly.mdx" +```mdx title="DocForHumansOnly.mdx" import { Meta } from '@storybook/addon-docs/blocks'; @@ -131,5 +137,3 @@ import { Meta } from '@storybook/addon-docs/blocks'; - [MCP server API](./mcp/api.mdx) - [Sharing your MCP server](./mcp/sharing.mdx) - [Manifests](./manifests.mdx) - - diff --git a/docs/ai/index.mdx b/docs/ai/index.mdx index 809e20ad6533..5e6efb14d5ba 100644 --- a/docs/ai/index.mdx +++ b/docs/ai/index.mdx @@ -4,11 +4,13 @@ sidebar: order: 5 title: AI --- - + - While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](./manifests.mdx) and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](./manifests.mdx) and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + diff --git a/docs/ai/manifests.mdx b/docs/ai/manifests.mdx index 5ecab4c782f3..5dad6f60c9a9 100644 --- a/docs/ai/manifests.mdx +++ b/docs/ai/manifests.mdx @@ -5,9 +5,11 @@ sidebar: --- - While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the manifests and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the manifests and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + @@ -38,11 +40,15 @@ type ButtonProps = { * Button is used for user interactions that do not navigate to another route. * For navigation, use [Link](?path=/docs/link--default) instead. */ -export const Button: React.FC = ({ onClick }) => { /* ... */ }; +export const Button: React.FC = ({ onClick }) => { + //... +}; ``` - - Check the [best practices](./best-practices.mdx) guide for tips on writing effective JSDoc comments for your components and other ways to provide helpful context for the agents. + + +Check the [best practices](./best-practices.mdx) guide for tips on writing effective JSDoc comments for your components and other ways to provide helpful context for the agents. + If a story file declares [`subcomponents`](../writing-stories/stories-for-multiple-components.mdx#subcomponents), the components manifest will also include a `subcomponents` object for that component. This gives agents supplemental API documentation for child components, even when those subcomponents are only meant to be used together with the parent. @@ -53,7 +59,9 @@ The raw JSON components manifest can be accessed at `http://localhost:6006/manif Example components manifest entry - While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + +While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + ```json @@ -76,9 +84,7 @@ The raw JSON components manifest can be accessed at `http://localhost:6006/manif } ], "import": "import { Button } from \"@mealdrop/ui\";", - "jsDocTags": { - - }, + "jsDocTags": {}, "description": "Primary UI component for user interaction", "reactDocgen": { "description": "Primary UI component for user interaction", @@ -219,6 +225,7 @@ The raw JSON components manifest can be accessed at `http://localhost:6006/manif } } ``` + ## Docs (MDX) manifest @@ -228,14 +235,18 @@ The docs manifest is generated from the [MDX files](../writing-docs/mdx.mdx) in The raw JSON docs manifest can be accessed at `http://localhost:6006/manifests/docs.json` (your port may vary) when your Storybook is running or at the `/manifests/docs.json` route in a built Storybook. - Check the [best practices](./best-practices.mdx) guide for tips on writing effective documentation and providing helpful context for the agents. + +Check the [best practices](./best-practices.mdx) guide for tips on writing effective documentation and providing helpful context for the agents. +
Example docs manifest entry - While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + +While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + ```json @@ -251,6 +262,7 @@ The raw JSON docs manifest can be accessed at `http://localhost:6006/manifests/d } } ``` +
## Debugging @@ -271,7 +283,7 @@ You can also remove an entire component from the manifest by removing the tag in Similarly, to exclude an entire MDX docs page from the manifests, you can remove the `manifest` tag from the page's metadata: -```jsx title="DocForHumansOnly.mdx" +```mdx title="DocForHumansOnly.mdx" import { Meta } from '@storybook/addon-docs/blocks'; diff --git a/docs/ai/mcp/api.mdx b/docs/ai/mcp/api.mdx index 7d825cab597a..dc94a2efaf0e 100644 --- a/docs/ai/mcp/api.mdx +++ b/docs/ai/mcp/api.mdx @@ -4,11 +4,13 @@ sidebar: order: 2 title: API --- - + - While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + @@ -31,7 +33,7 @@ Type: } ``` -Default: +Default: ```ts { diff --git a/docs/ai/mcp/overview.mdx b/docs/ai/mcp/overview.mdx index dab0b2f8a7a4..f487fc94e7d4 100644 --- a/docs/ai/mcp/overview.mdx +++ b/docs/ai/mcp/overview.mdx @@ -6,9 +6,11 @@ sidebar: --- - While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + diff --git a/docs/ai/mcp/sharing.mdx b/docs/ai/mcp/sharing.mdx index 0ec12a48d753..633787a464c7 100644 --- a/docs/ai/mcp/sharing.mdx +++ b/docs/ai/mcp/sharing.mdx @@ -6,9 +6,11 @@ sidebar: --- - While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and [MCP server](./overview.mdx)) are currently only supported for [React](?renderer=react) projects. - Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. +While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and [MCP server](./overview.mdx)) are currently only supported for [React](?renderer=react) projects. + +Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + @@ -56,11 +58,11 @@ import { createStorybookMcpHandler } from '@storybook/mcp'; const storybookMcpHandler = await createStorybookMcpHandler(); export async function handleRequest(request: Request): Promise { - if (new URL(request.url).pathname === '/mcp') { - return storybookMcpHandler(request); - } + if (new URL(request.url).pathname === '/mcp') { + return storybookMcpHandler(request); + } - return new Response('Not found', { status: 404 }); + return new Response('Not found', { status: 404 }); } ``` diff --git a/docs/api/arg-types.mdx b/docs/api/arg-types.mdx index 83e46470f211..8a802bfc0142 100644 --- a/docs/api/arg-types.mdx +++ b/docs/api/arg-types.mdx @@ -1,8 +1,7 @@ --- -title: "ArgTypes" +title: ArgTypes sidebar: order: 3 - title: ArgTypes --- ArgTypes specify the behavior of [args](../writing-stories/args.mdx). By specifying the type of an arg, you constrain the values that it can accept and provide information about args that are not explicitly set (i.e., [description](#description)). @@ -35,28 +34,16 @@ For most Storybook projects, argTypes are [automatically inferred](#automatic-ar ArgTypes are most often specified at the component level, in the [meta (or default export)](../writing-stories/index.mdx#default-export) of the CSF file: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - They can apply to all stories when specified at the project (global) level, in the `preview.*` configuration file: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Or they can apply only to a [specific story](../writing-stories/index.mdx#defining-stories): -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `argTypes` Type: @@ -110,12 +97,8 @@ Default: Specify the behavior of the [controls panel](../essentials/controls.mdx) for the arg. If you specify a string, it's used as the [`type`](#controltype) of the control. If you specify an object, you can provide additional configuration. Specifying `false` will prevent the control from rendering. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - #### `control.type` Type: `ControlType | null` @@ -143,10 +126,9 @@ Specifies the type of control used to change the arg value with the [controls pa | | `'text'` | Provides a freeform text input.
`{ control: 'text' }` | - The `date` control will convert the date into a UNIX timestamp when the value - changes. It's a known limitation that will be fixed in a future release. If - you need to represent the actual date, you'll need to update the story's - implementation and convert the value into a date object. + +The `date` control will convert the date into a UNIX timestamp when the value changes. It's a known limitation that will be fixed in a future release. If you need to represent the actual date, you'll need to update the story's implementation and convert the value into a date object. + #### `control.accept` @@ -193,12 +175,8 @@ Default: [Inferred](#automatic-argtype-inference) Describe the arg. (If you intend to describe the type of the arg, you should use [`table.type`](#tabletype), instead.) -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `if` Type: @@ -215,12 +193,8 @@ Type: Conditionally render an argType based on the value of another [arg](../writing-stories/args.mdx) or [global](../essentials/toolbars-and-globals.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `mapping` Type: `{ [key: string]: { [option: string]: any } }` @@ -231,26 +205,19 @@ When dealing with non-primitive values, you'll notice that you'll run into some `mapping` doesn't have to be exhaustive. If the currently selected option is not listed, it's used verbatim. Can be used with [`control.labels`](#labels). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `name` Type: `string` The `argTypes` object uses the name of the arg as the key. By default, that key is used when displaying the argType in Storybook. You can override the displayed name by specifying a `name` property. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - Be careful renaming args in this way. Users of the component you're documenting will not be able to use the documented name as a property of your component and the actual name will not displayed. + +Be careful renaming args in this way. Users of the component you're documenting will not be able to use the documented name as a property of your component and the actual name will not displayed. For this reason, the `name` property is best used when defining an `argType` that is only used for documentation purposes and not an actual property of the component. For example, when [providing argTypes for each property of an object](https://stackblitz.com/edit/github-uplqzp?file=src/stories/Button.stories.tsx). @@ -264,12 +231,8 @@ Default: [Inferred](#automatic-argtype-inference) If the arg accepts a finite set of values, you can specify them with `options`. If those values are [complex](../essentials/controls.mdx#dealing-with-complex-values), like JSX elements, you can use [`mapping`](#mapping) to map them to string values. You can use [`control.labels`](#labels) to provide custom labels for the options. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `table` Type: @@ -294,12 +257,8 @@ Default: [Inferred](#automatic-argtype-inference) Specify how the arg is documented in the [`ArgTypes` doc block](./doc-blocks/doc-block-argtypes.mdx), [`Controls` doc block](./doc-blocks/doc-block-controls.mdx), and [Controls panel](../essentials/controls.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - #### `table.category` Type: `string` @@ -351,7 +310,7 @@ Type: `'boolean' | 'function' | 'number' | 'string' | 'symbol' | SBType` The full type of `SBType` is:
- SBType +SBType ```ts interface SBBaseType { @@ -360,31 +319,31 @@ interface SBBaseType { } type SBScalarType = SBBaseType & { - name: "boolean" | "string" | "number" | "function" | "symbol"; + name: 'boolean' | 'string' | 'number' | 'function' | 'symbol'; }; type SBArrayType = SBBaseType & { - name: "array"; + name: 'array'; value: SBType; }; type SBObjectType = SBBaseType & { - name: "object"; + name: 'object'; value: Record; }; type SBEnumType = SBBaseType & { - name: "enum"; + name: 'enum'; value: (string | number)[]; }; type SBIntersectionType = SBBaseType & { - name: "intersection"; + name: 'intersection'; value: SBType[]; }; type SBUnionType = SBBaseType & { - name: "union"; + name: 'union'; value: SBType[]; }; type SBOtherType = SBBaseType & { - name: "other"; + name: 'other'; value: string; }; @@ -406,12 +365,8 @@ Specifies the semantic type of the argType. When an argType is [inferred](#autom If you only need to specify the documented type, you should use [`table.type`](#tabletype), instead. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `defaultValue` (⛔️ **Deprecated**) @@ -420,8 +375,4 @@ Type: `any` Define the default value of the argType. Deprecated in favor of defining the [`arg`](../writing-stories/args.mdx) value directly. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/cli-options.mdx b/docs/api/cli-options.mdx index ccbd8fa769b4..9257662b9ca8 100644 --- a/docs/api/cli-options.mdx +++ b/docs/api/cli-options.mdx @@ -1,17 +1,18 @@ --- -title: 'CLI options' +title: CLI options hideRendererSelector: true sidebar: order: 8 - title: CLI options --- The Storybook command line interface (CLI) is the main tool you use to build and develop Storybook. - Storybook collects completely anonymous data to help us improve user experience. Participation is - optional, and you may [opt-out](../configure/telemetry.mdx#how-to-opt-out) if you'd not like to - share any information. + +Storybook collects completely anonymous data to help us improve user experience. Participation is +optional, and you may [opt-out](../configure/telemetry.mdx#how-to-opt-out) if you'd not like to +share any information. + ## CLI commands @@ -19,9 +20,11 @@ The Storybook command line interface (CLI) is the main tool you use to build and All of the following documentation is available in the CLI by running `storybook --help`. - Passing options to these commands works slightly differently if you're using npm instead of Yarn. - You must prefix all of your options with `--`. For example, `npm run storybook build -- -o - ./path/to/build --quiet`. + +Passing options to these commands works slightly differently if you're using npm instead of Yarn. +You must prefix all of your options with `--`. For example, `npm run storybook build -- -o +./path/to/build --quiet`. + ### `dev` @@ -42,7 +45,7 @@ Options include: | `--exact-port` | Attempts to run Storybook on the exact port number specified.
If the port is already in use, Storybook will exit with an error message.
`storybook dev -p 9009 --exact-port` | | `-h`, `--host [string]` | Host to run Storybook.
`storybook dev -h my-host.com` | | `-c`, `--config-dir [dir-name]` | Storybook configuration directory.
`storybook dev -c .storybook` | -| `--loglevel [level]` | Controls level of logging during build.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook dev --loglevel warn` | +| `--loglevel [level]` | Controls level of logging during build.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook dev --loglevel warn` | | `--https` | Serve Storybook over HTTPS. Note: You must provide your own certificate information.
`storybook dev --https` | | `--ssl-ca` | Provide an SSL certificate authority. (Optional with --https, required if using a self-signed certificate)
`storybook dev --ssl-ca my-certificate` | | `--ssl-cert` | Provide an SSL certificate. (Required with --https)
`storybook dev --ssl-cert my-ssl-certificate` | @@ -64,9 +67,11 @@ Options include: | `--preview-only` | Skips Storybook's manager from building and opens the app in "preview only" mode, which is designed to be used in [unsupported browsers](../sharing/publish-storybook.mdx#build-storybook-for-older-browsers).
`storybook dev --preview-only` | - With the release of Storybook 8, the `-s` CLI flag was removed. We recommend using the [static - directory](../configure/integration/images-and-assets.mdx#serving-static-files-via-storybook) - instead if you need to serve static files. + +With the release of Storybook 8, the `-s` CLI flag was removed. We recommend using the [static +directory](../configure/integration/images-and-assets.mdx#serving-static-files-via-storybook) +instead if you need to serve static files. + ### `build` @@ -85,7 +90,7 @@ Options include: | `-V`, `--version` | Output the version number.
`storybook build -V` | | `-o`, `--output-dir [dir-name]` | Directory where to store built files.
`storybook build -o /my-deployed-storybook` | | `-c`, `--config-dir [dir-name]` | Storybook configuration directory.
`storybook build -c .storybook` | -| `--loglevel [level]` | Controls level of logging during build.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`.
`storybook build --loglevel warn` | +| `--loglevel [level]` | Controls level of logging during build.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`.
`storybook build --loglevel warn` | | `--quiet` | Suppress verbose build output.
`storybook build --quiet` | | `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook build --debug` | | `--debug-webpack` | Display final webpack configurations for debugging purposes.
`storybook build --debug-webpack` | @@ -101,8 +106,10 @@ Options include: ### `init` - We recommend [`create-storybook`](#create-storybook) for new projects. The `init` command will - remain available for backwards compatibility. + +We recommend [`create-storybook`](#create-storybook) for new projects. The `init` command will +remain available for backwards compatibility. + Installs and initializes the specified version (e.g., `@latest`, `@8`, `@next`) of Storybook into your project. If no version is specified, the latest version is installed. Read more in the [installation guide](../get-started/install.mdx). @@ -123,7 +130,7 @@ Options include: | `-s`, `--skip-install` | Skips the dependency installation step. Used only when you need to configure Storybook manually.
`storybook init --skip-install` | | `-t`, `--type` | Defines the [framework](../configure/integration/frameworks.mdx) to use for your Storybook instance.
`storybook init --type solid` | | `-y`, `--yes` | Skips interactive prompts and automatically installs Storybook per specified version, including all features.
`storybook init --yes` | -| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test`, and `a11y`, space separated.
`storybook init --features docs test a11y` | +| `--features [...values]` | Use these features when installing, skipping the prompt. Supported values are `docs`, `test`, and `a11y`, space separated.
`storybook init --features docs test a11y` | | `--package-manager` | Sets the package manager to use when installing Storybook.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook init --package-manager pnpm` | | `--use-pnp` | Enables [Plug'n'Play](https://yarnpkg.com/features/pnp) support for Yarn. This option is only available when using Yarn as your package manager.
`storybook init --use-pnp` | | `-p`, `--parser` | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser).
Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`.
`storybook init --parser tsx` | @@ -131,7 +138,7 @@ Options include: | `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`storybook init --disable-telemetry` | | `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook init --enable-crash-reports` | | `--loglevel ` | Controls level of logging during initialization.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook init --loglevel debug` | -| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook init --logfile /tmp/debug-storybook.log` | +| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook init --logfile /tmp/debug-storybook.log` | | `--no-dev` | Complete the initialization of Storybook without running the Storybook dev server.
`storybook init --no-dev` | ### `add` @@ -144,15 +151,15 @@ storybook add [addon] [options] Options include: -| Option | Description | -| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information.
`storybook add --help` | -| `-c`, `--config-dir` | Storybook configuration directory.
`storybook migrate --config-dir .storybook` | -| `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook add [addon] --package-manager pnpm` | -| `-s`, `--skip-postinstall` | Skips post-install configuration. Used only when you need to configure the addon yourself.
`storybook add [addon] --skip-postinstall` | -| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook add --debug` | -| `--loglevel ` | Controls level of logging during addon installation.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook add [addon] --loglevel debug` | -| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook add [addon] --logfile /tmp/debug-storybook.log` | +| Option | Description | +| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information.
`storybook add --help` | +| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.
`storybook add --config-dir .storybook` | +| `--package-manager` | Sets the package manager to use when installing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook add [addon] --package-manager pnpm` | +| `-s`, `--skip-postinstall` | Skips post-install configuration. Used only when you need to configure the addon yourself.
`storybook add [addon] --skip-postinstall` | +| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook add --debug` | +| `--loglevel ` | Controls level of logging during addon installation.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook add [addon] --loglevel debug` | +| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook add [addon] --logfile /tmp/debug-storybook.log` | ### `remove` @@ -184,20 +191,20 @@ For example, `storybook@latest upgrade --dry-run` will perform a dry run (no act Options include: -| Option | Description | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information.
`storybook upgrade --help` | -| `-c, --config-dir ` | Directory or directories to find Storybook configurations
`storybook upgrade --config-dir .storybook` | -| `-n`, `--dry-run` | Checks for version upgrades without installing them.
`storybook upgrade --dry-run` | -| `-s`, `--skip-check` | Skips the migration check step during the upgrade process.
`storybook upgrade --skip-check` | -| `-y`, `--yes` | Skips interactive prompts and automatically upgrades Storybook to the latest version.
`storybook upgrade --yes` | -| `-f`,`--force` | Force the upgrade, skipping autoblockers check.
`storybook upgrade --force` | -| `--package-manager` | Sets the package manager to use when upgrading Storybook.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook upgrade --package-manager pnpm` | -| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook upgrade --debug` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`storybook upgrade --disable-telemetry` | -| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook upgrade --enable-crash-reports` | -| `-logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook upgrade --logfile /tmp/debug-storybook.log` | -| `--loglevel ` | Define log level: `debug`, `error`, `info`, `silent`, `trace`, or `warn` (default: `info`).
`storybook upgrade --loglevel debug` | +| Option | Description | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information.
`storybook upgrade --help` | +| `-c, --config-dir ` | Directory or directories to find Storybook configurations
`storybook upgrade --config-dir .storybook` | +| `-n`, `--dry-run` | Checks for version upgrades without installing them.
`storybook upgrade --dry-run` | +| `-s`, `--skip-check` | Skips the migration check step during the upgrade process.
`storybook upgrade --skip-check` | +| `-y`, `--yes` | Skips interactive prompts and automatically upgrades Storybook to the latest version.
`storybook upgrade --yes` | +| `-f`,`--force` | Force the upgrade, skipping autoblockers check.
`storybook upgrade --force` | +| `--package-manager` | Sets the package manager to use when upgrading Storybook.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook upgrade --package-manager pnpm` | +| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook upgrade --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`storybook upgrade --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook upgrade --enable-crash-reports` | +| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook upgrade --logfile /tmp/debug-storybook.log` | +| `--loglevel ` | Define log level: `debug`, `error`, `info`, `silent`, `trace`, or `warn` (default: `info`).
`storybook upgrade --loglevel debug` | ### `migrate` @@ -208,25 +215,27 @@ storybook[@version] migrate [codemod] [options] ``` - The command requires the codemod name (e.g., `csf-2-to-3`) as an argument to apply the necessary - changes to your project. You can find the list of available codemods by running `storybook migrate - --list`. + +The command requires the codemod name (e.g., `csf-2-to-3`) as an argument to apply the necessary +changes to your project. You can find the list of available codemods by running `storybook migrate +--list`. + For example, `storybook@latest migrate csf-2-to-3 --dry-run`, checks your project to verify if the codemod can be applied without making any changes, providing you with a report of which files would be affected. Options include: -| Option | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `-h`, `--help` | Output usage information.
`storybook migrate --help` | -| `-c`, `--config-dir` | Storybook configuration directory.
`storybook migrate --config-dir .storybook` | -| `-n`, `--dry-run` | Verify the migration exists and show the files to which it will be applied.
`storybook migrate --dry-run` | -| `-l`, `--list` | Shows a list of available codemods.
`storybook migrate --list` | -| `-g`, `--glob` | Glob for files upon which to apply the codemods.
`storybook migrate --glob src/**/*.stories.tsx` | -| `-p`, `--parser` | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser).
Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`.
`storybook migrate --parser tsx` | -| `-r`, `--rename [from-to]` | Renames the files affected by the codemod to include the provided suffix.
`storybook migrate --rename ".js:.ts"` | -| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook migrate --debug` | +| Option | Description | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `-h`, `--help` | Output usage information.
`storybook migrate --help` | +| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.
`storybook migrate --config-dir .storybook` | +| `-n`, `--dry-run` | Verify the migration exists and show the files to which it will be applied.
`storybook migrate --dry-run` | +| `-l`, `--list` | Shows a list of available codemods.
`storybook migrate --list` | +| `-g`, `--glob` | Glob for files upon which to apply the codemods.
`storybook migrate --glob src/**/*.stories.tsx` | +| `-p`, `--parser` | Sets the [jscodeshift parser](https://github.com/facebook/jscodeshift#parser).
Available parsers include `babel`, `babylon`, `flow`, `ts`, and `tsx`.
`storybook migrate --parser tsx` | +| `-r`, `--rename [from-to]` | Renames the files affected by the codemod to include the provided suffix.
`storybook migrate --rename ".js:.ts"` | +| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook migrate --debug` | ### `automigrate` @@ -240,23 +249,23 @@ For example, `storybook@latest automigrate --dry-run` scans your project for pot Options include: -| Option | Description | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information.
`storybook automigrate --help` | -| `-c`, `--config-dir` | Storybook configuration directory.
`storybook automigrate --config-dir .storybook` | -| `-n`, `--dry-run` | Checks for available migrations without applying them.
`storybook automigrate --dry-run` | -| `-s`, `--skip-install` | Skip installing dependencies whenever applicable.
`storybook automigrate --skip-install` | -| `-y`, `--yes` | Applies available migrations automatically without prompting for confirmation.
`storybook automigrate --yes` | -| `-l`, `--list` | Shows a list of available automigrations.
`storybook automigrate --list` | -| `--package-manager` | Sets the package manager to use when running the auto migration.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook automigrate --package-manager pnpm` | -| `--renderer` | Specifies Storybook's renderer to use when running the automigration.
Useful for monorepo environments where multiple Storybook instances can exist in the same project.
`storybook automigrate --renderer vue` | -| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook automigrate --debug` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`storybook automigrate --disable-telemetry` | -| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook automigrate --enable-crash-reports` | +| Option | Description | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information.
`storybook automigrate --help` | +| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.
`storybook automigrate --config-dir .storybook` | +| `-n`, `--dry-run` | Checks for available migrations without applying them.
`storybook automigrate --dry-run` | +| `-s`, `--skip-install` | Skip installing dependencies whenever applicable.
`storybook automigrate --skip-install` | +| `-y`, `--yes` | Applies available migrations automatically without prompting for confirmation.
`storybook automigrate --yes` | +| `-l`, `--list` | Shows a list of available automigrations.
`storybook automigrate --list` | +| `--package-manager` | Sets the package manager to use when running the auto migration.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook automigrate --package-manager pnpm` | +| `--renderer` | Specifies Storybook's renderer to use when running the automigration.
Useful for monorepo environments where multiple Storybook instances can exist in the same project.
`storybook automigrate --renderer vue` | +| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook automigrate --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`storybook automigrate --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook automigrate --enable-crash-reports` | ### `doctor` -Performs a health check on your Storybook project for common issues (e.g., duplicate dependencies, incompatible addons or mismatched versions) and provides suggestions on how to fix them. Applicable when [upgrading](../releases/upgrading.mdx#verifying-the-upgrade) Storybook versions. +Performs a health check on your Storybook project for common issues (e.g., duplicate dependencies, incompatible addons or mismatched versions) and provides suggestions on how to fix them. Applicable when [upgrading](../releases/upgrading.mdx#automatic-health-check) Storybook versions. ```shell storybook doctor [options] @@ -264,12 +273,12 @@ storybook doctor [options] Options include: -| Option | Description | -| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information.
`storybook doctor --help` | -| `-c`, `--config-dir` | Storybook configuration directory.
`storybook doctor --config-dir .storybook` | -| `--package-manager` | Sets the package manager to use when running the health check.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook doctor --package-manager pnpm` | -| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook doctor --debug` | +| Option | Description | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `-h`, `--help` | Output usage information.
`storybook doctor --help` | +| `-c`, `--config-dir [dir-name]` | Storybook configuration directory.
`storybook doctor --config-dir .storybook` | +| `--package-manager` | Sets the package manager to use when running the health check.
Available package managers include `npm`, `yarn`, and `pnpm`.
`storybook doctor --package-manager pnpm` | +| `--debug` | Outputs more logs in the CLI to assist debugging.
`storybook doctor --debug` | ### `info` @@ -315,7 +324,7 @@ Options include: | Option | Description | | --------------------------------- | ------------------------------------------------------ | | `-o`, `--output-file ` | JSON file to output index | -| `-c`, `--config-dir ` | Storybook configuration directory | +| `-c`, `--config-dir ` | Storybook configuration directory | | `--quiet` | Suppress verbose build output | | `--loglevel ` | Control level of logging during build | | `--disable-telemetry` | Disables Storybook's telemetry | @@ -346,8 +355,10 @@ Options include: | `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`storybook sandbox --enable-crash-reports` | - If you're looking for a hosted version of the available sandboxes, see - [storybook.new](https://storybook.new). + +If you're looking for a hosted version of the available sandboxes, see +[storybook.new](https://storybook.new). + ## `create-storybook` @@ -377,6 +388,6 @@ Options include: | `--debug` | Outputs more logs in the CLI to assist debugging.
`create storybook --debug` | | `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#how-to-opt-out).
`create storybook --disable-telemetry` | | `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.mdx#crash-reports-disabled-by-default).
`create storybook --enable-crash-reports` | -| `--loglevel ` | Controls level of logging during initialization.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`storybook init --loglevel debug` | -| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`storybook init --logfile /tmp/debug-storybook.log` | +| `--loglevel ` | Controls level of logging during initialization.
Available options: `trace`, `debug`, `info` (default), `warn`, `error`, `silent`
`create storybook --loglevel debug` | +| `--logfile [path]` | Write all debug logs to the specified file at the end of the run. Defaults to debug-storybook.log when [path] is not provided.
`create storybook --logfile /tmp/debug-storybook.log` | | `--no-dev` | Complete the initialization of Storybook without running the Storybook dev server.
`create storybook --no-dev` | diff --git a/docs/api/csf/csf-next.mdx b/docs/api/csf/csf-next.mdx index d5dfa5dd811e..15ab36d98fbe 100644 --- a/docs/api/csf/csf-next.mdx +++ b/docs/api/csf/csf-next.mdx @@ -1,5 +1,5 @@ --- -title: 'Component Story Format (CSF)' +title: Component Story Format (CSF) isTab: true tab: order: 2 @@ -8,8 +8,10 @@ tab: - - CSF Next is currently only supported in [React](?renderer=react), [Vue](?renderer=vue), [Angular](?renderer=angular), and [Web Components](?renderer=web-components) projects. + + +CSF Next is currently in [preview](../../releases/features.mdx#preview) and only supported in [React](?renderer=react), [Vue](?renderer=vue), [Angular](?renderer=angular), and [Web Components](?renderer=web-components) projects. + @@ -17,7 +19,9 @@ tab: - This is a [**preview**](../../releases/features.mdx#preview) feature and (though unlikely) the API may change in future releases. We [welcome feedback](https://github.com/storybookjs/storybook/discussions/30112) and contributions to help improve this feature. + +This is a [**preview**](../../releases/features.mdx#preview) feature and (though unlikely) the API may change in future releases. We [welcome feedback](https://github.com/storybookjs/storybook/discussions/30112) and contributions to help improve this feature. + CSF Next is the next evolution of Storybook's Component Story Format (CSF). This new API uses a pattern called factory functions to provide full type safety to your Storybook stories, making it easier to configure addons correctly and unlocking the full potential of Storybook's features. @@ -69,7 +73,9 @@ export default definePreview({ ``` - The preview configuration will be automatically updated to reference the [necessary addons](#preview-addons) when installing an addon via `npx storybook add ` or running `storybook dev`. + +The preview configuration will be automatically updated to reference the [necessary addons](#preview-addons) when installing an addon via `npx storybook add ` or running `storybook dev`. + ### `preview.meta` @@ -86,7 +92,7 @@ const meta = preview.meta({ parameters: { // type-safe! layout: 'centered', - } + }, }); ``` @@ -114,8 +120,8 @@ To configure subpath imports, add the following to your `package.json`: ```json title="package.json" { "imports": { - "#*": ["./*", "./*.ts", "./*.tsx"], - }, + "#*": ["./*", "./*.ts", "./*.tsx"] + } } ``` @@ -147,7 +153,11 @@ type CustomProps = React.ComponentProps & { customProp: string }; const meta = preview.type<{ args: CustomProps }>().meta({ component: Button, // 👇 Correct types - render: ({ customProp, ...args }) => <>{customProp} ; ``` -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - {/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Description } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; {/* Shows the description for the default export (the meta). - If that didn't have any comments, it would show the - comments from the component instead */} +If that didn't have any comments, it would show the +comments from the component instead */} {/* Shows the description for the Primary export */} ``` - {/* prettier-ignore-end */} diff --git a/docs/api/doc-blocks/doc-block-icongallery.mdx b/docs/api/doc-blocks/doc-block-icongallery.mdx index 533bdede03d4..741c0975031e 100644 --- a/docs/api/doc-blocks/doc-block-icongallery.mdx +++ b/docs/api/doc-blocks/doc-block-icongallery.mdx @@ -1,8 +1,7 @@ --- -title: 'IconGallery' +title: IconGallery sidebar: order: 6 - title: IconGallery --- The `IconGallery` block enables you to easily document React icon components associated with your project, displayed in a neat grid. @@ -13,9 +12,7 @@ The `IconGallery` block enables you to easily document React icon components ass To document a set of icons, use the `IconGallery` block to display them in a grid. Each icon is wrapped in an `IconItem` block, enabling you to specify its properties, such as the name and the icon itself. -{/* prettier-ignore-start */} - -```md title="Iconography.mdx" +```mdx title="Iconography.mdx" import { Meta, IconGallery, IconItem } from '@storybook/addon-docs/blocks'; import { Icon as IconExample } from './Icon'; @@ -40,16 +37,16 @@ import { Icon as IconExample } from './Icon'; - + - + - + @@ -58,15 +55,11 @@ import { Icon as IconExample } from './Icon'; ``` -{/* prettier-ignore-end */} - ### Automate icon documentation If you're working on a project that contains a large number of icons that you want to document, you can extend the `IconGallery` block, wrap `IconItem` in a loop, and iterate over the icons you want to document, including their properties. For example: -{/* prettier-ignore-start */} - -```md title="Iconography.mdx" +```mdx title="Iconography.mdx" import { Meta, IconGallery, IconItem } from '@storybook/addon-docs/blocks'; import { Icon as IconExample } from './Icon'; @@ -83,8 +76,6 @@ import * as icons from './icons'; ``` -{/* prettier-ignore-end */} - ## IconGallery ```js diff --git a/docs/api/doc-blocks/doc-block-markdown.mdx b/docs/api/doc-blocks/doc-block-markdown.mdx index 8d34cadc9325..48015af01dd9 100644 --- a/docs/api/doc-blocks/doc-block-markdown.mdx +++ b/docs/api/doc-blocks/doc-block-markdown.mdx @@ -1,8 +1,7 @@ --- -title: 'Markdown' +title: Markdown sidebar: order: 7 - title: Markdown --- The `Markdown` block allows you to import and include plain markdown in your MDX files. @@ -11,23 +10,17 @@ The `Markdown` block allows you to import and include plain markdown in your MD When importing markdown files, it’s important to use the `?raw` suffix on the import path to ensure the content is imported as-is, and isn’t being evaluated: -{/* prettier-ignore-start */} - ````md title="README.md" # Button Primary UI component for user interaction ```js -import { Button } from "@storybook/design-system"; +import { Button } from '@storybook/design-system'; ``` ```` -{/* prettier-ignore-end */} - -{/* prettier-ignore-start */} - -```md title="Header.mdx" +```mdx title="Header.mdx" // DON'T do this, will error import ReadMe from './README.md'; // DO this, will work @@ -35,13 +28,11 @@ import ReadMe from './README.md?raw'; import { Markdown } from '@storybook/addon-docs/blocks'; -# A header +# A header {ReadMe} ``` -{/* prettier-ignore-end */} - ## Markdown ```js @@ -64,24 +55,18 @@ Specifies the options passed to the underlying [`markdown-to-jsx` library](https From a purely technical standpoint, we could include the imported markdown directly in the MDX file like this: -{/* prettier-ignore-start */} - -```md +```mdx {/* THIS WON'T WORK, THIS IS TO DEMONSTRATE AN ERROR */} import ReadMe from './README.md'; -# A header +# A header {ReadMe} ``` -{/* prettier-ignore-end */} - However, there are small syntactical differences between plain markdown and MDX2. MDX2 is more strict and will interpret certain content as JSX expressions. Here’s an example of a perfectly valid markdown file, that would break if it was handled directly by MDX2: -{/* prettier-ignore-start */} - ```md # A header @@ -90,12 +75,8 @@ However, there are small syntactical differences between plain markdown and MDX2 ``` -{/* prettier-ignore-end */} - Furthermore, MDX2 wraps all strings on newlines in `p` tags or similar, meaning that content would render differently between a plain `.md` file and an `.mdx` file. -{/* prettier-ignore-start */} - ```md # A header @@ -111,5 +92,3 @@ The example above will remain as-is in plain markdown, but MDX2 will compile it

Some text

``` - -{/* prettier-ignore-end */} diff --git a/docs/api/doc-blocks/doc-block-meta.mdx b/docs/api/doc-blocks/doc-block-meta.mdx index cf686e569941..39812947df3f 100644 --- a/docs/api/doc-blocks/doc-block-meta.mdx +++ b/docs/api/doc-blocks/doc-block-meta.mdx @@ -1,28 +1,25 @@ --- -title: 'Meta' +title: Meta sidebar: order: 8 - title: Meta --- The `Meta` block is used to [attach](#attached-vs-unattached) a custom MDX docs page alongside a component’s list of stories. It doesn’t render any content, but serves two purposes in an MDX file: -* Attaches the MDX file to a component and its stories, or -* Controls the location of the unattached docs entry in the sidebar. +- Attaches the MDX file to a component and its stories, or +- Controls the location of the unattached docs entry in the sidebar. -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - - The Meta block doesn’t render anything visible. + +The Meta block doesn’t render anything visible. + ## Meta @@ -45,35 +42,28 @@ Type: `string` Sets the name of the [attached](#attached-vs-unattached) doc entry. You can attach more than one MDX file to the same component in the sidebar by setting different names for each file's `Meta`. -{/* prettier-ignore-start */} - -```md title="Component.mdx" +```mdx title="Component.mdx" import { Meta } from '@storybook/addon-docs/blocks'; import * as ComponentStories from './component.stories'; {/* This MDX file is now called "Special Docs" */} + ``` -{/* prettier-ignore-end */} - ### `of` Type: CSF file exports Specifies which CSF file is [attached](#attached-vs-unattached) to this MDX file. Pass the **full set of exports** from the CSF file (not the default export!). -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Story } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - Attaching an MDX file to a component’s stories with the `of` prop serves two purposes: 1. Ensures the MDX content appears in the sidebar inside the component’s story list. By default, it will be named whatever the `docs.defaultName` (which defaults to `"Docs"`) option is set to in `main.js`. But this can be overridden with the [`name` prop](#name). @@ -81,7 +71,7 @@ Attaching an MDX file to a component’s stories with the `of` prop serves two p - The `of` prop is optional. If you don’t want to attach a specific CSF file to this MDX file, you can either use the `title` prop to control the location, or emit `Meta` entirely, and let [autotitle](../../configure/user-interface/sidebar-and-urls.mdx#csf-30-auto-titles) decide where it goes. +The `of` prop is optional. If you don’t want to attach a specific CSF file to this MDX file, you can either use the `title` prop to control the location, or emit `Meta` entirely, and let [autotitle](../../configure/user-interface/sidebar-and-urls.mdx#csf-30-auto-titles) decide where it goes. @@ -92,22 +82,18 @@ Type: `string` Sets the title of an [unattached](#attached-vs-unattached) MDX file. {/* prettier-ignore-start */} - -```md -{/* Introduction.mdx */} - +```mdx title="Introduction.mdx" import { Meta } from '@storybook/addon-docs/blocks'; {/* Override the docs entry's location in the sidebar with title */} ``` - {/* prettier-ignore-end */} - If you want to change the sorting of the docs entry with the component’s stories, use [Story Sorting](../../writing-stories/naming-components-and-hierarchy.mdx#sorting-stories), or add specific MDX files to your `stories` field in `main.js` in order. - +If you want to change the sorting of the docs entry with the component’s stories, use [Story Sorting](../../writing-stories/naming-components-and-hierarchy.mdx#sorting-stories), or add specific MDX files to your `stories` field in `main.js` in order. + ## Attached vs. unattached diff --git a/docs/api/doc-blocks/doc-block-primary.mdx b/docs/api/doc-blocks/doc-block-primary.mdx index 0179811d4bc1..2c6b72e4833f 100644 --- a/docs/api/doc-blocks/doc-block-primary.mdx +++ b/docs/api/doc-blocks/doc-block-primary.mdx @@ -1,17 +1,14 @@ --- -title: 'Primary' +title: Primary sidebar: order: 9 - title: Primary --- The `Primary` block displays the primary (first defined in the stories file) story, in a [`Story`](./doc-block-story.mdx) block. It is typically rendered immediately under the title in a docs entry. ![Screenshot of Primary block](../../_assets/api/doc-block-primary.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Primary } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; @@ -20,8 +17,6 @@ import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - ## Primary ```js diff --git a/docs/api/doc-blocks/doc-block-source.mdx b/docs/api/doc-blocks/doc-block-source.mdx index 782e26fe114d..4ee44a526d87 100644 --- a/docs/api/doc-blocks/doc-block-source.mdx +++ b/docs/api/doc-blocks/doc-block-source.mdx @@ -1,17 +1,14 @@ --- -title: 'Source' +title: Source sidebar: order: 10 - title: Source --- The `Source` block is used to render a snippet of source code directly. ![Screenshot of Source block](../../_assets/api/doc-block-source.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Source } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; @@ -20,8 +17,6 @@ import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - ## Source ```js @@ -29,27 +24,20 @@ import { Source } from '@storybook/addon-docs/blocks'; ```
- Configuring with props and parameters - - ℹ️ Like most blocks, the `Source` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../../writing-stories/parameters.mdx) in the block's namespace, `parameters.docs.source`. +Configuring with props and parameters - The following `language` configurations are equivalent: +ℹ️ Like most blocks, the `Source` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../../writing-stories/parameters.mdx) in the block's namespace, `parameters.docs.source`. - {/* prettier-ignore-start */} +The following `language` configurations are equivalent: - + - {/* prettier-ignore-end */} - - {/* prettier-ignore-start */} - - ```md title="ButtonDocs.mdx" - - ``` +```mdx title="ButtonDocs.mdx" + +``` - {/* prettier-ignore-end */} +The example above applied the parameter at the [story](../../writing-stories/parameters.mdx#story-parameters) level, but it could also be applied at the [component](../../writing-stories/parameters.mdx#component-parameters) (or meta) level or [project](../../writing-stories/parameters.mdx#global-parameters) level. - The example above applied the parameter at the [story](../../writing-stories/parameters.mdx#story-parameters) level, but it could also be applied at the [component](../../writing-stories/parameters.mdx#component-parameters) (or meta) level or [project](../../writing-stories/parameters.mdx#global-parameters) level.
### `code` @@ -60,22 +48,20 @@ Default: `parameters.docs.source.code` Provides the source code to be rendered. -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Source } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; - +}`} +/> ``` -{/* prettier-ignore-end */} - ### `dark` Type: `boolean` @@ -86,30 +72,30 @@ Determines if the snippet is rendered in dark mode. - Light mode is only supported when the `Source` block is rendered independently. When rendered as part of a [`Canvas` block](./doc-block-canvas.mdx)—like it is in [autodocs](../../writing-docs/autodocs.mdx)—it will always use dark mode. +Light mode is only supported when the `Source` block is rendered independently. When rendered as part of a [`Canvas` block](./doc-block-canvas.mdx)—like it is in [autodocs](../../writing-docs/autodocs.mdx)—it will always use dark mode. - - ### `excludeDecorators` + - Type: `boolean` +### `excludeDecorators` + +Type: `boolean` - Default: `parameters.docs.source.excludeDecorators` +Default: `parameters.docs.source.excludeDecorators` - Determines if [decorators](../../writing-stories/decorators.mdx) are rendered in the source code snippet. - +Determines if [decorators](../../writing-stories/decorators.mdx) are rendered in the source code snippet. + + ### `language` Type: {/* prettier-ignore-start */} - ```ts 'jsextra' | 'jsx' | 'json' | 'yml' | 'md' | 'bash' | 'css' | 'html' | 'tsx' | 'typescript' | 'graphql' ``` - {/* prettier-ignore-end */} Default: `parameters.docs.source.language` or `'jsx'` @@ -143,12 +129,12 @@ Default: `parameters.docs.source.type` or `'auto'` Specifies how the source code is rendered. -* **auto**: Same as **dynamic**, if the story's `render` function accepts args inputs and **dynamic** is supported by the framework in use; otherwise same as **code** -* **code**: Renders the value of [`code` prop](#code), otherwise renders static story source -* **dynamic**: Renders the story source with dynamically updated arg values +- **auto**: Same as **dynamic**, if the story's `render` function accepts args inputs and **dynamic** is supported by the framework in use; otherwise same as **code** +- **code**: Renders the value of [`code` prop](#code), otherwise renders static story source +- **dynamic**: Renders the story source with dynamically updated arg values - Note that dynamic snippets will only work if the story uses [`args`](../../writing-stories/args.mdx) and the [`Story` block](./doc-block-story.mdx) for that story is rendered along with the `Source` block. - +Note that dynamic snippets will only work if the story uses [`args`](../../writing-stories/args.mdx) and the [`Story` block](./doc-block-story.mdx) for that story is rendered along with the `Source` block. + diff --git a/docs/api/doc-blocks/doc-block-stories.mdx b/docs/api/doc-blocks/doc-block-stories.mdx index 27916a1ec2ee..c1a24775d251 100644 --- a/docs/api/doc-blocks/doc-block-stories.mdx +++ b/docs/api/doc-blocks/doc-block-stories.mdx @@ -1,17 +1,14 @@ --- -title: 'Stories' +title: Stories sidebar: order: 11 - title: Stories --- The `Stories` block renders the full collection of stories in a stories file. ![Screenshot of Stories block](../../_assets/api/doc-block-stories.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Stories } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; @@ -20,8 +17,6 @@ import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - ## Stories ```js @@ -40,8 +35,8 @@ Determines if the collection of stories includes the primary (first) story. - If a stories file contains only one story and `includePrimary={true}`, the `Stories` block will render nothing to avoid a potentially confusing situation. - +If a stories file contains only one story and `includePrimary={true}`, the `Stories` block will render nothing to avoid a potentially confusing situation. + ### `title` diff --git a/docs/api/doc-blocks/doc-block-story.mdx b/docs/api/doc-blocks/doc-block-story.mdx index d4822d9e223b..ad171e40488f 100644 --- a/docs/api/doc-blocks/doc-block-story.mdx +++ b/docs/api/doc-blocks/doc-block-story.mdx @@ -1,8 +1,7 @@ --- -title: 'Story' +title: Story sidebar: order: 12 - title: Story --- [Stories](../../writing-stories/index.mdx) are Storybook's fundamental building blocks. @@ -11,15 +10,13 @@ In Storybook Docs, you can render any of your stories from your CSF files in the - Typically you want to use the [`Canvas` block](./doc-block-canvas.mdx) to render a story with a surrounding border and the source block, but you can use the `Story` block to render just the story. - +Typically you want to use the [`Canvas` block](./doc-block-canvas.mdx) to render a story with a surrounding border and the source block, but you can use the `Story` block to render just the story. + ![Screenshot of Story block](../../_assets/api/doc-block-story.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx"+ +```mdx title="ButtonDocs.mdx" import { Meta, Story } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; @@ -28,8 +25,6 @@ import * as ButtonStories from './Button.stories'; ``` -{/* prettier-ignore-end */} - ## Story ```js @@ -37,27 +32,20 @@ import { Story } from '@storybook/addon-docs/blocks'; ```
- Configuring with props and parameters - - ℹ️ Like most blocks, the `Story` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../../writing-stories/parameters.mdx) in the block's namespace, `parameters.docs.story`. - - The following `autoplay` configurations are equivalent: - - {/* prettier-ignore-start */} +Configuring with props and parameters - +ℹ️ Like most blocks, the `Story` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../../writing-stories/parameters.mdx) in the block's namespace, `parameters.docs.story`. - {/* prettier-ignore-end */} +The following `autoplay` configurations are equivalent: - {/* prettier-ignore-start */} + - ```md title="ButtonDocs.mdx" - - ``` +```mdx title="ButtonDocs.mdx" + +``` - {/* prettier-ignore-end */} +The example above applied the parameter at the [story](../../writing-stories/parameters.mdx#story-parameters) level, but it could also be applied at the [component](../../writing-stories/parameters.mdx#component-parameters) (or meta) level or [project](../../writing-stories/parameters.mdx#global-parameters) level. - The example above applied the parameter at the [story](../../writing-stories/parameters.mdx#story-parameters) level, but it could also be applied at the [component](../../writing-stories/parameters.mdx#component-parameters) (or meta) level or [project](../../writing-stories/parameters.mdx#global-parameters) level.
### `autoplay` @@ -73,7 +61,9 @@ Because all stories render simultaneously in docs entries, play functions can pe However, if you know your play function is “safe” to run in docs, you can use this prop to run it automatically. - If a story uses [`mount` in its play function](../../writing-tests/interaction-testing.mdx#run-code-before-the-component-gets-rendered), it will not render in docs unless `autoplay` is set to `true`. + +If a story uses [`mount` in its play function](../../writing-tests/interaction-testing.mdx#run-code-before-the-component-gets-rendered), it will not render in docs unless `autoplay` is set to `true`. + ### `height` @@ -94,8 +84,8 @@ Determines whether the story is rendered `inline` (in the same browser frame as - Setting the `inline` option to false will prevent the associated [controls](./doc-block-controls.mdx) from updating the story within the documentation page. This is a known limitation of the current implementation and will be addressed in a future release. - +Setting the `inline` option to false will prevent the associated [controls](./doc-block-controls.mdx) from updating the story within the documentation page. This is a known limitation of the current implementation and will be addressed in a future release. + ### `meta` @@ -107,8 +97,7 @@ Specifies the CSF file to which the story is associated. You can render a story from a CSF file that you haven’t attached to the MDX file (via `Meta`) by using the `meta` prop. Pass the **full set of exports** from the CSF file (not the default export!). {/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta, Story } from '@storybook/addon-docs/blocks'; import * as ButtonStories from './Button.stories'; import * as HeaderStories from './Header.stories'; @@ -116,10 +105,9 @@ import * as HeaderStories from './Header.stories'; {/* Although this MDX file is largely concerned with Button, - it can render Header stories too */} +it can render Header stories too */} ``` - {/* prettier-ignore-end */} ### `of` @@ -127,4 +115,3 @@ import * as HeaderStories from './Header.stories'; Type: Story export Specifies which story is rendered by the `Story` block. If no `of` is defined and the MDX file is [attached](./doc-block-meta.mdx#attached-vs-unattached), the primary (first) story will be rendered. - diff --git a/docs/api/doc-blocks/doc-block-subtitle.mdx b/docs/api/doc-blocks/doc-block-subtitle.mdx index afe93fa17e28..f8a7ed56410d 100644 --- a/docs/api/doc-blocks/doc-block-subtitle.mdx +++ b/docs/api/doc-blocks/doc-block-subtitle.mdx @@ -1,24 +1,19 @@ --- -title: 'Subtitle' +title: Subtitle sidebar: order: 13 - title: Subtitle --- The `Subtitle` block can serve as a secondary heading for your docs entry. ![Screenshot of Subtitle block](../../_assets/api/doc-block-title-subtitle-description.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Subtitle } from '@storybook/addon-docs/blocks'; This is the subtitle ``` -{/* prettier-ignore-end */} - ## Subtitle ```js diff --git a/docs/api/doc-blocks/doc-block-tableofcontents.mdx b/docs/api/doc-blocks/doc-block-tableofcontents.mdx index 96b282affee7..d32d9b3a55d8 100644 --- a/docs/api/doc-blocks/doc-block-tableofcontents.mdx +++ b/docs/api/doc-blocks/doc-block-tableofcontents.mdx @@ -1,8 +1,7 @@ --- -title: 'TableOfContents' +title: TableOfContents sidebar: order: 14 - title: TableOfContents --- The `TableOfContents` block renders a table of contents for the current documentation page, allowing users to navigate between sections quickly. It appears as a fixed sidebar on the right side of the documentation page and is hidden on smaller screens (below 768px). @@ -11,7 +10,7 @@ The table of contents is enabled and configured via the `docs.toc` [parameter](. - For a step-by-step guide on enabling and customizing the table of contents, see the [Generate a table of contents](../../writing-docs/autodocs.mdx#generate-a-table-of-contents) section in the Autodocs documentation. +For a step-by-step guide on enabling and customizing the table of contents, see the [Generate a table of contents](../../writing-docs/autodocs.mdx#generate-a-table-of-contents) section in the Autodocs documentation. @@ -19,20 +18,12 @@ The table of contents is enabled and configured via the `docs.toc` [parameter](. Enable the table of contents globally in your Storybook preview configuration: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - You can also enable or disable it for specific components in their stories file: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `toc` parameter options The `docs.toc` parameter accepts either `true` (to enable with defaults) or an object with the following properties: @@ -83,8 +74,4 @@ Type: `object` Provides additional configuration options passed directly to the underlying [`Tocbot`](https://tscanlin.github.io/tocbot/) library. These options are not guaranteed to remain available in future versions of Storybook. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/doc-blocks/doc-block-title.mdx b/docs/api/doc-blocks/doc-block-title.mdx index 1c40d97e7499..1c9b17c464c2 100644 --- a/docs/api/doc-blocks/doc-block-title.mdx +++ b/docs/api/doc-blocks/doc-block-title.mdx @@ -1,24 +1,19 @@ --- -title: 'Title' +title: Title sidebar: order: 15 - title: Title --- The `Title` block serves as the primary heading for your docs entry. It is typically used to provide the component or page name. ![Screenshot of Title block](../../_assets/api/doc-block-title-subtitle-description.png) -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Title } from '@storybook/addon-docs/blocks'; This is the title ``` -{/* prettier-ignore-end */} - ## Title ```js diff --git a/docs/api/doc-blocks/doc-block-typeset.mdx b/docs/api/doc-blocks/doc-block-typeset.mdx index f7c49b5dabe6..056efbcd8b79 100644 --- a/docs/api/doc-blocks/doc-block-typeset.mdx +++ b/docs/api/doc-blocks/doc-block-typeset.mdx @@ -1,17 +1,14 @@ --- -title: 'Typeset' +title: Typeset sidebar: order: 16 - title: Typeset --- The `Typeset` block helps document the fonts used throughout your project. ![Screenshot of Typeset block](../../_assets/api/doc-block-typeset.png) -{/* prettier-ignore-start */} - -```md title="Typography.mdx" +```mdx title="Typography.mdx" import { Meta, Typeset } from '@storybook/addon-docs/blocks'; @@ -65,8 +62,6 @@ export const SampleText = 'Lorem ipsum dolor sit amet, consectetur adipiscing el /> ``` -{/* prettier-ignore-end */} - ## Typeset ```js diff --git a/docs/api/doc-blocks/doc-block-unstyled.mdx b/docs/api/doc-blocks/doc-block-unstyled.mdx index addc5f677448..1b9ec7dd51be 100644 --- a/docs/api/doc-blocks/doc-block-unstyled.mdx +++ b/docs/api/doc-blocks/doc-block-unstyled.mdx @@ -1,19 +1,16 @@ --- -title: 'Unstyled' +title: Unstyled sidebar: order: 17 - title: Unstyled --- The `Unstyled` block is a special block that disables Storybook's default styling in MDX docs wherever it is added. By default, most elements (like `h1`, `p`, etc.) in docs have a few default styles applied to ensure the docs look good. However, sometimes you might want some of your content to not have these styles applied. In those cases, wrap the content with the `Unstyled` block to remove the default styles. -{/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" -import { Meta, Unstyled } from "@storybook/addon-docs/blocks"; -import { Header } from "./Header.tsx"; +```mdx title="ButtonDocs.mdx" +import { Meta, Unstyled } from '@storybook/addon-docs/blocks'; +import { Header } from './Header.tsx'; @@ -24,9 +21,9 @@ import { Header } from "./Header.tsx"; > This block quote will not be styled - ... neither will this paragraph, nor the following component (which contains an \): +... neither will this paragraph, nor the following component (which contains an \): -
+
``` @@ -39,24 +36,22 @@ Yields: - The other blocks like [`Story`](./doc-block-story.mdx) and [`Canvas`](./doc-block-canvas.mdx) are already unstyled, so there’s no need to wrap those in the `Unstyled` block to ensure that Storybook’s styles don’t bleed into the stories. However, if you import your components directly in the MDX, you most likely want to wrap them in the Unstyled block. - +The other blocks like [`Story`](./doc-block-story.mdx) and [`Canvas`](./doc-block-canvas.mdx) are already unstyled, so there’s no need to wrap those in the `Unstyled` block to ensure that Storybook’s styles don’t bleed into the stories. However, if you import your components directly in the MDX, you most likely want to wrap them in the Unstyled block. + - Due to how CSS inheritance works it’s best to always add the Unstyled block to the root of your MDX, and not nested into other elements. The following example will cause some Storybook styles like `color` to be inherited into `CustomComponent` because they are applied to the root `div`: - {/* prettier-ignore-start */} +Due to how CSS inheritance works it’s best to always add the Unstyled block to the root of your MDX, and not nested into other elements. The following example will cause some Storybook styles like `color` to be inherited into `CustomComponent` because they are applied to the root `div`: - ```md -
- - - -
- ``` +```md +
+ + + +
+``` - {/* prettier-ignore-end */} ## Unstyled @@ -71,4 +66,4 @@ import { Unstyled } from '@storybook/addon-docs/blocks'; Type: `React.ReactNode` -Provides the content to which you do *not* want to apply default docs styles. +Provides the content to which you do _not_ want to apply default docs styles. diff --git a/docs/api/doc-blocks/doc-block-useof.mdx b/docs/api/doc-blocks/doc-block-useof.mdx index a47517330bad..455d74e8f6db 100644 --- a/docs/api/doc-blocks/doc-block-useof.mdx +++ b/docs/api/doc-blocks/doc-block-useof.mdx @@ -1,8 +1,7 @@ --- -title: 'useOf' +title: useOf sidebar: order: 18 - title: useOf --- The default blocks supplied by Storybook do not fit all use cases, so you might want to write your own blocks. @@ -35,8 +34,7 @@ export const StoryName = ({ of }) => { ``` {/* prettier-ignore-start */} - -```md title="ButtonDocs.mdx" +```mdx title="ButtonDocs.mdx" import { Meta } from '@storybook/addon-docs/blocks'; import { StoryName } from '../.storybook/blocks/StoryName'; import * as ButtonStories from './Button.stories'; @@ -52,24 +50,19 @@ import * as ButtonStories from './Button.stories'; {/* Renders "Button" */} ``` - {/* prettier-ignore-end */} ## useOf ### Type -{/* prettier-ignore-start */} - ```ts ( moduleExportOrType: ModuleExport | 'story' | 'meta' | 'component', - validTypes?: Array<'story' | 'meta' | 'component'> -) => EnhancedResolvedModuleExportType + validTypes?: Array<'story' | 'meta' | 'component'>, +) => EnhancedResolvedModuleExportType; ``` -{/* prettier-ignore-end */} - ### Parameters #### `moduleExportOrType` @@ -82,9 +75,9 @@ Provides the story export, meta export, component export, or CSF file exports fr When the custom block is in an [attached doc](./doc-block-meta.mdx#attached-vs-unattached), it’s also possible to get the primary (first) story, meta, or component by passing in a string instead. This is useful as a fallback, so the `of` prop can be omitted in your block. The most common pattern is using this as `useOf(props.of || 'story')` which will fall back to the primary story if no `of` prop is defined. -* `useOf('story')` returns the annotated primary story in attached mode; error in unattached mode -* `useOf('meta')` returns the annotated meta in attached mode; error in unattached mode -* `useOf('component')` returns the annotated component specified in the meta in attached mode; error in unattached mode +- `useOf('story')` returns the annotated primary story in attached mode; error in unattached mode +- `useOf('meta')` returns the annotated meta in attached mode; error in unattached mode +- `useOf('component')` returns the annotated component specified in the meta in attached mode; error in unattached mode #### `validTypes` diff --git a/docs/api/doc-blocks/index.mdx b/docs/api/doc-blocks/index.mdx index d71c4eb2a286..d0279fecff66 100644 --- a/docs/api/doc-blocks/index.mdx +++ b/docs/api/doc-blocks/index.mdx @@ -2,5 +2,4 @@ title: Doc Blocks sidebar: order: 5 - title: Doc Blocks ---- \ No newline at end of file +--- diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 36be8e4c9114..59b274404ecc 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -1,17 +1,15 @@ --- -title: 'API references' +title: API references hideRendererSelector: true sidebar: order: 12 title: API ---- - -{/* +note: | We intentionally do not use markdown tables here because the required formatting (one row per line) makes it very difficult to read, particularly when comparing changes. Also, using HTML directly allows us to apply a consistent width to the first column. However, this means the links won't work when viewing in GitHub. :( -*/} +--- An overview of all available API references for Storybook. @@ -61,6 +59,7 @@ An overview of all available API references for Storybook. version of your Storybook. + @@ -102,6 +101,7 @@ An overview of all available API references for Storybook. Parameters are static metadata used to configure your stories addons in Storybook. They are specified at the story, meta (component), project (global) levels. + @@ -124,5 +124,6 @@ An overview of all available API references for Storybook. your project. + diff --git a/docs/api/main-config/index.mdx b/docs/api/main-config/index.mdx index 18d625a5de5f..750ca73e9eab 100644 --- a/docs/api/main-config/index.mdx +++ b/docs/api/main-config/index.mdx @@ -2,5 +2,4 @@ title: 'main.js|ts configuration' sidebar: order: 1 - title: main.js|ts configuration ---- \ No newline at end of file +--- diff --git a/docs/api/main-config/main-config-addons.mdx b/docs/api/main-config/main-config-addons.mdx index cb2df239cdf0..b1eb51ff4dc5 100644 --- a/docs/api/main-config/main-config-addons.mdx +++ b/docs/api/main-config/main-config-addons.mdx @@ -1,8 +1,7 @@ --- -title: 'addons' +title: addons sidebar: order: 4 - title: addons --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,8 +12,4 @@ Registers the [addons](../../addons/install-addons.mdx) loaded by Storybook. For each addon's available options, see their respective [documentation](https://storybook.js.org/integrations). -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-babel-default.mdx b/docs/api/main-config/main-config-babel-default.mdx index 25a763fe8006..ba7f14ddacf1 100644 --- a/docs/api/main-config/main-config-babel-default.mdx +++ b/docs/api/main-config/main-config-babel-default.mdx @@ -1,8 +1,7 @@ --- -title: 'babelDefault' +title: babelDefault sidebar: order: 6 - title: babelDefault --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,16 +12,12 @@ Type: `(config: Babel.Config, options: Options) => Babel.Config | Promise - To adjust your Storybook's Babel setup directly—not via an addon—use [`babel`](./main-config-babel.mdx) instead. - - +To adjust your Storybook's Babel setup directly—not via an addon—use [`babel`](./main-config-babel.mdx) instead. -{/* prettier-ignore-start */} + -{/* prettier-ignore-end */} - ## `Babel.Config` The options provided by [Babel](https://babeljs.io/docs/options) are only applicable if you've enabled the [`@storybook/addon-webpack5-compiler-babel`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-babel) addon. diff --git a/docs/api/main-config/main-config-babel.mdx b/docs/api/main-config/main-config-babel.mdx index 88203adceb03..0ee8759f4df2 100644 --- a/docs/api/main-config/main-config-babel.mdx +++ b/docs/api/main-config/main-config-babel.mdx @@ -1,8 +1,7 @@ --- -title: 'babel' +title: babel sidebar: order: 5 - title: babel --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,24 +12,20 @@ Customize Storybook's [Babel](https://babeljs.io/) setup. - [Addon authors](../../addons/writing-presets.mdx#babel) should use [`babelDefault`](./main-config-babel-default.mdx) instead, which is applied to the preview config before any user presets have been applied. +[Addon authors](../../addons/writing-presets.mdx#babel) should use [`babelDefault`](./main-config-babel-default.mdx) instead, which is applied to the preview config before any user presets have been applied. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `Babel.Config` The options provided by [Babel](https://babeljs.io/docs/options) are only applicable if you've enabled the [`@storybook/addon-webpack5-compiler-babel`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-babel) addon. - If you have an existing Babel configuration file (e.g., `.babelrc`), it will be automatically detected and used by Storybook without any additional configuration required. - +If you have an existing Babel configuration file (e.g., `.babelrc`), it will be automatically detected and used by Storybook without any additional configuration required. + ## `Options` diff --git a/docs/api/main-config/main-config-build.mdx b/docs/api/main-config/main-config-build.mdx index ebad98b2b0f9..4fe1c2fd50b2 100644 --- a/docs/api/main-config/main-config-build.mdx +++ b/docs/api/main-config/main-config-build.mdx @@ -1,8 +1,7 @@ --- -title: 'build' +title: build sidebar: order: 7 - title: build --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -32,7 +31,7 @@ Configures Storybook's production builds for performance testing purposes by dis - The options documented on this page are automatically enabled when the `--test` flag is provided to the [`storybook build`](../cli-options.mdx#build) command. We encourage you to override these options only if you need to disable a specific feature for your project or if you are debugging a build issue. +The options documented on this page are automatically enabled when the `--test` flag is provided to the [`storybook build`](../cli-options.mdx#build) command. We encourage you to override these options only if you need to disable a specific feature for your project or if you are debugging a build issue. @@ -42,80 +41,52 @@ Type: `boolean` Excludes the `@storybook/addon-docs/blocks` module from the build, which generates automatic documentation with [Docs Blocks](../../writing-docs/doc-blocks.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disabledAddons` Type: `string[]` Sets the list of addons that will be disabled in the build output. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableMDXEntries` Type: `boolean` Enabling this option removes user-written documentation entries in MDX format from the build. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableAutoDocs` Type: `boolean` Prevents automatic documentation generated with the [autodocs](../../writing-docs/autodocs.mdx) feature from being included in the build. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableDocgen` Type: `boolean` Disables [automatic argType](../arg-types.mdx#automatic-argtype-inference) and component property inference with any of the supported static analysis tools based on the framework you are using. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableSourcemaps` Type: `boolean` Overrides the default behavior of generating source maps for the build. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ### `test.disableTreeShaking` Type: `boolean` Disables [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) in the build. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-core.mdx b/docs/api/main-config/main-config-core.mdx index e2531467af84..005796834ab2 100644 --- a/docs/api/main-config/main-config-core.mdx +++ b/docs/api/main-config/main-config-core.mdx @@ -1,8 +1,7 @@ --- -title: 'core' +title: core sidebar: order: 8 - title: core --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -34,12 +33,8 @@ Default: `[]` Configures the allowed hosts for the Storybook dev server, used for Origin and Host header validation. Storybook's localhost and local network (or [`--host`](../cli-options.mdx#dev)) addresses are always allowed. Use this when accessing your local Storybook instance through a reverse proxy (e.g. your webapp dev server). Set to `true` to disable hostname validation (insecure). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `builder` Type: @@ -55,16 +50,14 @@ Type: Configures Storybook's builder, [Vite](../../builders/vite.mdx) or [Webpack](../../builders/webpack.mdx). - With the new [Framework API](../new-frameworks.mdx), [`framework.options.builder`](./main-config-framework.mdx#optionsbuilder) is now the preferred way to configure the builder. - You should only use `core.builder.options` if you need to configure a builder that is not part of a framework. - +With the new [Framework API](../new-frameworks.mdx), [`framework.options.builder`](./main-config-framework.mdx#optionsbuilder) is now the preferred way to configure the builder. -{/* prettier-ignore-start */} +You should only use `core.builder.options` if you need to configure a builder that is not part of a framework. - + -{/* prettier-ignore-end */} + ## `channelOptions` @@ -85,7 +78,6 @@ Configures the channel used by Storybook to communicate between the manager and Only two properties are likely to be used: - ### `channelOptions.maxDepth` Type: `number` @@ -102,75 +94,51 @@ Enable CORS headings to run document in a "secure context". See [SharedArrayBuff This enables these headers in development-mode: -* `Cross-Origin-Opener-Policy: same-origin` -* `Cross-Origin-Embedder-Policy: require-corp` - -{/* prettier-ignore-start */} +- `Cross-Origin-Opener-Policy: same-origin` +- `Cross-Origin-Embedder-Policy: require-corp` -{/* prettier-ignore-end */} - ## `disableProjectJson` Type: `boolean` Disables the generation of `project.json`, a file containing Storybook metadata -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `disableTelemetry` Type: `boolean` Disables Storybook's [telemetry collection](../../configure/telemetry.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `disableWebpackDefaults` Type: `boolean` Disables Storybook's default Webpack configuration. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `disableWhatsNewNotifications` Type: `boolean` Disables the "What's New" notifications in the UI for new Storybook versions and ecosystem updates (e.g., [addons](https://storybook.js.org/integrations/), [content](https://storybook.js.org/blog/), etc.). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `enableCrashReports` Type: `boolean` Enable crash reports to be sent to Storybook [telemetry](../../configure/telemetry.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `renderer` Type: `RendererName` diff --git a/docs/api/main-config/main-config-docs.mdx b/docs/api/main-config/main-config-docs.mdx index 7c28850020ae..a31599bb5ef3 100644 --- a/docs/api/main-config/main-config-docs.mdx +++ b/docs/api/main-config/main-config-docs.mdx @@ -1,8 +1,7 @@ --- -title: 'docs' +title: docs sidebar: order: 9 - title: docs --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -26,20 +25,12 @@ Default: `'Docs'` Name used for generated documentation pages. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `docsMode` Type: `boolean` Only show documentation pages in the sidebar (usually set with the `--docs` CLI flag). -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-env.mdx b/docs/api/main-config/main-config-env.mdx index 5ed5392bf429..487fe6c911f2 100644 --- a/docs/api/main-config/main-config-env.mdx +++ b/docs/api/main-config/main-config-env.mdx @@ -1,8 +1,7 @@ --- -title: 'env' +title: env sidebar: order: 10 - title: env --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,8 +10,4 @@ Type: `(config: { [key: string]: string }) => { [key: string]: string }` Defines custom Storybook [environment variables](../../configure/environment-variables.mdx#using-storybook-configuration). -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-features.mdx b/docs/api/main-config/main-config-features.mdx index 1b9fa4e69c13..1c2c55dcd262 100644 --- a/docs/api/main-config/main-config-features.mdx +++ b/docs/api/main-config/main-config-features.mdx @@ -1,8 +1,7 @@ --- -title: 'features' +title: features sidebar: order: 11 - title: features --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -32,6 +31,7 @@ Type: viewport?: boolean; } ``` + @@ -55,6 +55,7 @@ Type: viewport?: boolean; } ``` + @@ -77,8 +78,8 @@ Type: viewport?: boolean; } ``` - + Enables Storybook's additional features. @@ -110,12 +111,8 @@ Default: `true` Filter args with a "target" on the type from the render function. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `backgrounds` Type: `boolean` @@ -160,12 +157,8 @@ Type: `boolean` Set `NODE_ENV` to `'development'` in built Storybooks for better testing and debugging capabilities. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `experimentalCodeExamples` @@ -186,14 +179,10 @@ Unlike the current implementation, this method reads the actual stories source f Type: `boolean` -Enable the [experimental `.test` method with the CSF Next format](../csf/csf-next#storytest). - -{/* prettier-ignore-start */} +Enable the [experimental `.test` method with the CSF Next format](../csf/csf-next.mdx#storytest). -{/* prettier-ignore-end */} - ## `highlight` @@ -218,12 +207,8 @@ Type: `boolean` Apply decorators from preview.js before decorators from addons or frameworks. [More information](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#changed-decorator-order-between-previewjs-and-addonsframeworks). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `measure` Type: `boolean` diff --git a/docs/api/main-config/main-config-framework.mdx b/docs/api/main-config/main-config-framework.mdx index 3b2a2e7b38e4..6da060baaa5b 100644 --- a/docs/api/main-config/main-config-framework.mdx +++ b/docs/api/main-config/main-config-framework.mdx @@ -1,8 +1,7 @@ --- -title: 'framework' +title: framework sidebar: order: 2 - title: framework --- (**Required**) @@ -13,12 +12,8 @@ Type: `FrameworkName | { name: FrameworkName; options?: FrameworkOptions }` Configures Storybook based on a set of [framework-specific](../../configure/integration/frameworks.mdx) settings. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `name` Type: `string` diff --git a/docs/api/main-config/main-config-indexers.mdx b/docs/api/main-config/main-config-indexers.mdx index 9fce870fcc6c..042fe1759dbc 100644 --- a/docs/api/main-config/main-config-indexers.mdx +++ b/docs/api/main-config/main-config-indexers.mdx @@ -1,14 +1,15 @@ --- -title: 'indexers' +title: indexers sidebar: order: 12 - title: indexers --- (⚠️ **Experimental**) - While this feature is experimental, it must be specified by the `experimental_indexers` property of [`StorybookConfig`](./main-config.mdx). + +While this feature is experimental, it must be specified by the `experimental_indexers` property of [`StorybookConfig`](./main-config.mdx). + Parent: [main.js|ts configuration](./main-config.mdx) @@ -21,12 +22,8 @@ The indexers API is an advanced feature that allows you to customize Storybook's They are defined as a function that returns the full list of indexers, including the existing ones. This allows you to add your own indexer to the list, or to replace an existing one: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Unless your indexer is doing something relatively trivial (e.g. [indexing stories with a different naming convention](../../configure/user-interface/sidebar-and-urls.mdx#story-indexers)), in addition to indexing the file, you will likely need to [transpile it to CSF](#transpiling-to-csf) so that Storybook can read them in the browser. ## `Indexer` @@ -157,7 +154,7 @@ Default: Auto-generated from [`title`](#title) Define the custom id for meta of the entry. -If specified, the export default (meta) in the CSF file *must* have a corresponding `id` property, to be correctly matched. +If specified, the export default (meta) in the CSF file _must_ have a corresponding `id` property, to be correctly matched. ##### `name` @@ -183,12 +180,8 @@ Determines the location of the entry in the sidebar. Most of the time, you should **not** specify a title, so that your indexer will use the default naming behavior. When specifying a title, you **must** use the [`makeTitle`](#maketitle) function provided in [`IndexerOptions`](#indexeroptions) to also use this behavior. For example, here's an indexer that merely appends a "Custom" prefix to the title derived from the file name: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ##### `__id` Type: `string` @@ -203,7 +196,7 @@ Only use this if you need to override the auto-generated id. ## Transpiling to CSF -The value of [`importPath`](#importpath) in an [`IndexInput`](#indexinput) must resolve to a [CSF](../csf/index.mdx) file. Most custom indexers, however, are only necessary because the input is *not* CSF. Therefore, you will likely need to transpile the input to CSF, so that Storybook can read it in the browser and render your stories. +The value of [`importPath`](#importpath) in an [`IndexInput`](#indexinput) must resolve to a [CSF](../csf/index.mdx) file. Most custom indexers, however, are only necessary because the input is _not_ CSF. Therefore, you will likely need to transpile the input to CSF, so that Storybook can read it in the browser and render your stories. Transpiling the custom source format to CSF is beyond the scope of this documentation. This transpilation is often done at the builder level ([Vite](../../builders/vite.mdx) and/or [Webpack](../../builders/webpack.mdx)), and we recommend using [unplugin](https://github.com/unjs/unplugin) to create plugins for multiple builders. @@ -270,234 +263,227 @@ export const Primary = { }; ``` -### Examples +## Examples Some example usages of custom indexers include:
- Generating stories dynamically from fixture data or API endpoints - - This indexer generates stories for components based on JSON fixture data. It looks for `*.stories.json` files in the project, adds them to the index and separately converts their content to CSF. - - {/* prettier-ignore-start */} +Generating stories dynamically from fixture data or API endpoints - +This indexer generates stories for components based on JSON fixture data. It looks for `*.stories.json` files in the project, adds them to the index and separately converts their content to CSF. - {/* prettier-ignore-end */} + - An example input JSON file could look like this: +An example input JSON file could look like this: - ```json - { - "Button": { - "componentPath": "./button/Button.jsx", - "stories": { - "Primary": { - "args": { - "primary": true - }, - "Secondary": { - "args": { - "primary": false - } +```json +{ + "Button": { + "componentPath": "./button/Button.jsx", + "stories": { + "Primary": { + "args": { + "primary": true + } + }, + "Secondary": { + "args": { + "primary": false } } - }, - "Dialog": { - "componentPath": "./dialog/Dialog.jsx", - "stories": { - "Closed": {}, - "Open": { - "args": { - "isOpen": true - } - }, + } + }, + "Dialog": { + "componentPath": "./dialog/Dialog.jsx", + "stories": { + "Closed": {}, + "Open": { + "args": { + "isOpen": true + } } } } - ``` +} +``` - A builder plugin will then need to transform the JSON file into a regular CSF file. This transformation could be done with a Vite plugin similar to this: +A builder plugin will then need to transform the JSON file into a regular CSF file. This transformation could be done with a Vite plugin similar to this: - ```ts - // vite-plugin-storybook-json-stories.ts +```ts +// vite-plugin-storybook-json-stories.ts - import type { PluginOption } from 'vite'; - import fs from 'fs/promises'; +import type { PluginOption } from 'vite'; +import fs from 'fs/promises'; - function JsonStoriesPlugin(): PluginOption { - return { - name: 'vite-plugin-storybook-json-stories', - load(id) { - if (!id.startsWith('virtual:jsonstories')) { - return; - } +function JsonStoriesPlugin(): PluginOption { + return { + name: 'vite-plugin-storybook-json-stories', + load(id) { + if (!id.startsWith('virtual:jsonstories')) { + return; + } - const [, fileName, componentName] = id.split('--'); - const content = JSON.parse(fs.readFileSync(fileName)); + const [, fileName, componentName] = id.split('--'); + const content = JSON.parse(fs.readFileSync(fileName)); - const { componentPath, stories } = getComponentStoriesFromJson(content, componentName); + const { componentPath, stories } = getComponentStoriesFromJson(content, componentName); - return ` - import ${componentName} from '${componentPath}'; + return ` + import ${componentName} from '${componentPath}'; - export default { component: ${componentName} }; + export default { component: ${componentName} }; + + ${stories.map((story) => `export const ${story.name} = ${story.config};\n`)} + `; + }, + }; +} +``` - ${stories.map((story) => `export const ${story.name} = ${story.config};\n`)} - `; - }, - }; - } - ```
- Generating stories with an alternative API +Generating stories with an alternative API + +You can use a custom indexer and builder plugin to create your API to define stories extending the CSF format. To learn more, see the following [proof of concept](https://stackblitz.com/edit/github-h2rgfk?file=README.md) to set up a custom indexer to generate stories dynamically. It contains everything needed to support such a feature, including the indexer, a Vite plugin, and a Webpack loader. - You can use a custom indexer and builder plugin to create your API to define stories extending the CSF format. To learn more, see the following [proof of concept](https://stackblitz.com/edit/github-h2rgfk?file=README.md) to set up a custom indexer to generate stories dynamically. It contains everything needed to support such a feature, including the indexer, a Vite plugin, and a Webpack loader.
- Defining stories in non-JavaScript language +Defining stories in non-JavaScript language - Custom indexers can be used for an advanced purpose: defining stories in any language, including template languages, and converting the files to CSF. To see examples of this in action, you can refer to [`@storybook/addon-svelte-csf`](https://github.com/storybookjs/addon-svelte-csf) for Svelte template syntax and [`storybook-vue-addon`](https://github.com/tobiasdiez/storybook-vue-addon) for Vue template syntax. -
+Custom indexers can be used for an advanced purpose: defining stories in any language, including template languages, and converting the files to CSF. To see examples of this in action, you can refer to [`@storybook/addon-svelte-csf`](https://github.com/storybookjs/addon-svelte-csf) for Svelte template syntax and [`storybook-vue-addon`](https://github.com/tobiasdiez/storybook-vue-addon) for Vue template syntax. +
- Adding sidebar links from a URL collection - - The indexer API is flexible enough to let you process arbitrary content, so long as your framework tooling can transform the exports in that content into actual stories it can run. This advanced example demonstrates how you can create a custom indexer to process a collection of URLs, extract the title and URL from each page, and render them as sidebar links in the UI. Implemented with Svelte, it can be adapted to any framework. - - Start by creating the URL collection file (i.e., `src/MyLinks.url.js`) with a list of URLs listed as named exports. The indexer will use the export name as the story title and the value as the unique identifier. - - ```js title="MyLinks.url.js" - export default {}; - - export const DesignTokens = 'https://www.designtokens.org/'; - export const CobaltUI = 'https://cobalt-ui.pages.dev/'; - export const MiseEnMode = 'https://mode.place/'; - export const IndexerAPI = 'https://github.com/storybookjs/storybook/discussions/23176'; - ``` - - Adjust your Vite configuration file to include a custom plugin complementing the indexer. This will allow Storybook to process and import the URL collection file as stories. - - ```ts title="vite.config.ts" - import * as acorn from 'acorn'; - import * as walk from 'acorn-walk'; - import { defineConfig, type Plugin } from 'vite'; - import { svelte } from '@sveltejs/vite-plugin-svelte'; - - function StorybookUrlLinksPlugin(): Plugin { - return { - name: 'storybook-url-links', - async transform(code: string, id: string) { - if (id.endsWith('.url.js')) { - const ast = acorn.parse(code, { - ecmaVersion: 2020, - sourceType: 'module', - }); - - const namedExports: string[] = []; - let defaultExport = 'export default {};'; - - walk.simple(ast, { - // Extracts the named exports, those represent our stories, and for each of them, we'll return a valid Svelte component. - ExportNamedDeclaration(node: acorn.ExportNamedDeclaration) { - if ( - node.declaration && - node.declaration.type === 'VariableDeclaration' - ) { - node.declaration.declarations.forEach((declaration) => { - if ('name' in declaration.id) { - namedExports.push(declaration.id.name); - } - }); - } - }, - // Preserve our default export. - ExportDefaultDeclaration(node: acorn.ExportDefaultDeclaration) { - defaultExport = code.slice(node.start, node.end); - }, - }); - - return { - code: ` - import RedirectBack from '../../.storybook/components/RedirectBack.svelte'; - ${namedExports - .map( - (name) => - `export const ${name} = () => new RedirectBack();` - ) - .join('\n')} - ${defaultExport} - `, - map: null, - }; - } - }, - }; - } +Adding sidebar links from a URL collection - export default defineConfig({ - plugins: [StorybookUrlLinksPlugin(), svelte()], - }) - ``` - - Update your Storybook configuration (i.e., `.storybook/main.js|ts`) to include the custom indexer. - - ```ts title=".storybook/main.js|ts" - // Replace your-framework with the framework you are using, e.g. sveltekit or svelte-vite - import type { StorybookConfig } from '@storybook/your-framework'; - import type { Indexer } from 'storybook/internal/types'; - - const urlIndexer: Indexer = { - test: /\.url\.js$/, - createIndex: async (fileName, { makeTitle }) => { - const fileData = await import(fileName); - - return Object.entries(fileData) - .filter(([key]) => key != 'default') - .map(([name, url]) => { - return { - type: 'docs', - importPath: fileName, - exportName: name, - title: makeTitle(name) - .replace(/([a-z])([A-Z])/g, '$1 $2') - .trim(), - __id: `url--${name}--${encodeURIComponent(url as string)}`, - tags: ['!autodocs', 'url'] - }; +The indexer API is flexible enough to let you process arbitrary content, so long as your framework tooling can transform the exports in that content into actual stories it can run. This advanced example demonstrates how you can create a custom indexer to process a collection of URLs, extract the title and URL from each page, and render them as sidebar links in the UI. Implemented with Svelte, it can be adapted to any framework. + +Start by creating the URL collection file (i.e., `src/MyLinks.url.js`) with a list of URLs listed as named exports. The indexer will use the export name as the story title and the value as the unique identifier. + +```js title="MyLinks.url.js" +export default {}; + +export const DesignTokens = 'https://www.designtokens.org/'; +export const CobaltUI = 'https://cobalt-ui.pages.dev/'; +export const MiseEnMode = 'https://mode.place/'; +export const IndexerAPI = 'https://github.com/storybookjs/storybook/discussions/23176'; +``` + +Adjust your Vite configuration file to include a custom plugin complementing the indexer. This will allow Storybook to process and import the URL collection file as stories. + +```ts title="vite.config.ts" +import * as acorn from 'acorn'; +import * as walk from 'acorn-walk'; +import { defineConfig, type Plugin } from 'vite'; +import { svelte } from '@sveltejs/vite-plugin-svelte'; + +function StorybookUrlLinksPlugin(): Plugin { + return { + name: 'storybook-url-links', + async transform(code: string, id: string) { + if (id.endsWith('.url.js')) { + const ast = acorn.parse(code, { + ecmaVersion: 2020, + sourceType: 'module', + }); + + const namedExports: string[] = []; + let defaultExport = 'export default {};'; + + walk.simple(ast, { + // Extracts the named exports, those represent our stories, and for each of them, we'll return a valid Svelte component. + ExportNamedDeclaration(node: acorn.ExportNamedDeclaration) { + if (node.declaration && node.declaration.type === 'VariableDeclaration') { + node.declaration.declarations.forEach((declaration) => { + if ('name' in declaration.id) { + namedExports.push(declaration.id.name); + } + }); + } + }, + // Preserve our default export. + ExportDefaultDeclaration(node: acorn.ExportDefaultDeclaration) { + defaultExport = code.slice(node.start, node.end); + }, }); - } - }; - const config: StorybookConfig = { - stories: ['../src/**/*.stories.@(js|ts|svelte)', '../src/**/*.url.js'], - framework: { - name: '@storybook/svelte-vite', - options: {}, + return { + code: ` + import RedirectBack from '../../.storybook/components/RedirectBack.svelte'; + ${namedExports + .map((name) => `export const ${name} = () => new RedirectBack();`) + .join('\n')} + ${defaultExport} + `, + map: null, + }; + } }, - experimental_indexers: async (existingIndexers) => [urlIndexer, ...existingIndexers] }; - export default config; - ``` +} + +export default defineConfig({ + plugins: [StorybookUrlLinksPlugin(), svelte()], +}); +``` + +Update your Storybook configuration (i.e., `.storybook/main.js|ts`) to include the custom indexer. + +```ts title=".storybook/main.js|ts" +// Replace your-framework with the framework you are using, e.g. sveltekit or svelte-vite +import type { StorybookConfig } from '@storybook/your-framework'; +import type { Indexer } from 'storybook/internal/types'; + +const urlIndexer: Indexer = { + test: /\.url\.js$/, + createIndex: async (fileName, { makeTitle }) => { + const fileData = await import(fileName); + + return Object.entries(fileData) + .filter(([key]) => key != 'default') + .map(([name, url]) => { + return { + type: 'docs', + importPath: fileName, + exportName: name, + title: makeTitle(name) + .replace(/([a-z])([A-Z])/g, '$1 $2') + .trim(), + __id: `url--${name}--${encodeURIComponent(url as string)}`, + tags: ['!autodocs', 'url'], + }; + }); + }, +}; - Add a Storybook UI configuration file (i.e., `.storybook/manager.js|ts`) to render the indexed URLs as sidebar links in the UI: +const config: StorybookConfig = { + stories: ['../src/**/*.stories.@(js|ts|svelte)', '../src/**/*.url.js'], + framework: { + name: '@storybook/svelte-vite', + options: {}, + }, + experimental_indexers: async (existingIndexers) => [urlIndexer, ...existingIndexers], +}; +export default config; +``` - ```ts title=".storybook/manager.ts" - import { addons } from 'storybook/manager-api'; +Add a Storybook UI configuration file (i.e., `.storybook/manager.js|ts`) to render the indexed URLs as sidebar links in the UI: - import SidebarLabelWrapper from './components/SidebarLabelWrapper.tsx'; +```ts title=".storybook/manager.ts" +import { addons } from 'storybook/manager-api'; - addons.setConfig({ - sidebar: { - renderLabel: (item) => SidebarLabelWrapper({ item }), - }, - }); - ``` +import SidebarLabelWrapper from './components/SidebarLabelWrapper.tsx'; + +addons.setConfig({ + sidebar: { + renderLabel: (item) => SidebarLabelWrapper({ item }), + }, +}); +``` - This example's code and live demo are available on [StackBlitz](https://stackblitz.com/~/github.com/Sidnioulz/storybook-sidebar-urls). +This example's code and live demo are available on [StackBlitz](https://stackblitz.com/~/github.com/Sidnioulz/storybook-sidebar-urls).
diff --git a/docs/api/main-config/main-config-log-level.mdx b/docs/api/main-config/main-config-log-level.mdx index 064be3953f3f..aa8bc52c69a5 100644 --- a/docs/api/main-config/main-config-log-level.mdx +++ b/docs/api/main-config/main-config-log-level.mdx @@ -1,8 +1,7 @@ --- -title: 'logLevel' +title: logLevel sidebar: order: 13 - title: logLevel --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,8 +12,4 @@ Default: `'info'` Configures Storybook's logs in the browser terminal. Useful for debugging. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-manager-head.mdx b/docs/api/main-config/main-config-manager-head.mdx index 8af2641db0c1..29a1a47302e5 100644 --- a/docs/api/main-config/main-config-manager-head.mdx +++ b/docs/api/main-config/main-config-manager-head.mdx @@ -1,8 +1,7 @@ --- -title: 'managerHead' +title: managerHead sidebar: order: 14 - title: managerHead --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,14 +12,10 @@ Programmatically adjust the manager's `` of your Storybook. For example, l - If you don't need to programmatically adjust the manager head, you can add scripts and styles to `manager-head.html` instead. - +If you don't need to programmatically adjust the manager head, you can add scripts and styles to `manager-head.html` instead. + For example, you can conditionally add scripts or styles, depending on the environment: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-preview-annotations.mdx b/docs/api/main-config/main-config-preview-annotations.mdx index cf5a1bea2419..d2d66b889d9e 100644 --- a/docs/api/main-config/main-config-preview-annotations.mdx +++ b/docs/api/main-config/main-config-preview-annotations.mdx @@ -1,8 +1,7 @@ --- -title: 'previewAnnotations' +title: previewAnnotations sidebar: order: 15 - title: previewAnnotations --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -12,7 +11,9 @@ Type: `string[] | ((config: string[], options: Options) => string[] | Promise - Mostly used by [frameworks](../../contribute/framework.mdx#previewjs-example). Storybook users and [addon authors](../../addons/writing-presets.mdx) should add scripts to [`preview.js`](../../configure/index.mdx#configure-story-rendering) instead. + +Mostly used by [frameworks](../../contribute/framework.mdx#previewjs-example). Storybook users and [addon authors](../../addons/writing-presets.mdx) should add scripts to [`preview.js`](../../configure/index.mdx#configure-story-rendering) instead. + ```ts diff --git a/docs/api/main-config/main-config-preview-body.mdx b/docs/api/main-config/main-config-preview-body.mdx index 0777c1a35904..e904ffe2523f 100644 --- a/docs/api/main-config/main-config-preview-body.mdx +++ b/docs/api/main-config/main-config-preview-body.mdx @@ -1,8 +1,7 @@ --- -title: 'previewBody' +title: previewBody sidebar: order: 16 - title: previewBody --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -13,14 +12,10 @@ Programmatically adjust the [preview ``](../../configure/story-rendering.m - If you don't need to programmatically adjust the preview body, you can add scripts and styles to [`preview-body.html`](../../configure/story-rendering.mdx#adding-to-body) instead. - +If you don't need to programmatically adjust the preview body, you can add scripts and styles to [`preview-body.html`](../../configure/story-rendering.mdx#adding-to-body) instead. + For example, you can conditionally add scripts or styles, depending on the environment: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-preview-head.mdx b/docs/api/main-config/main-config-preview-head.mdx index 8745bc524edb..5bf40ecb9321 100644 --- a/docs/api/main-config/main-config-preview-head.mdx +++ b/docs/api/main-config/main-config-preview-head.mdx @@ -1,8 +1,7 @@ --- -title: 'previewHead' +title: previewHead sidebar: order: 17 - title: previewHead --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -12,13 +11,11 @@ Type: `(head: string) => string` Programmatically adjust the [preview ``](../../configure/story-rendering.mdx#adding-to-head) of your Storybook. Most often used by [addon authors](../../addons/writing-presets.mdx#ui-configuration). - If you don't need to programmatically adjust the preview head, you can add scripts and styles to [`preview-head.html`](../../configure/story-rendering.mdx#adding-to-head) instead. + +If you don't need to programmatically adjust the preview head, you can add scripts and styles to [`preview-head.html`](../../configure/story-rendering.mdx#adding-to-head) instead. + For example, you can conditionally add scripts or styles, depending on the environment: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-refs.mdx b/docs/api/main-config/main-config-refs.mdx index 33f7c69c5803..581f23503f80 100644 --- a/docs/api/main-config/main-config-refs.mdx +++ b/docs/api/main-config/main-config-refs.mdx @@ -1,8 +1,7 @@ --- -title: 'refs' +title: refs sidebar: order: 18 - title: refs --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -19,28 +18,16 @@ Type: Configures [Storybook composition](../../sharing/storybook-composition.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Using a function You can use a function to dynamically configure refs: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## Disable a ref Some package dependencies automatically [compose their Storybook in yours](../../sharing/package-composition.mdx). You can disable this behavior by setting `disable` to `true` for the package name: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-static-dirs.mdx b/docs/api/main-config/main-config-static-dirs.mdx index 0207e0b5e67d..f33305cd3d09 100644 --- a/docs/api/main-config/main-config-static-dirs.mdx +++ b/docs/api/main-config/main-config-static-dirs.mdx @@ -1,8 +1,7 @@ --- -title: 'staticDirs' +title: staticDirs sidebar: order: 19 - title: staticDirs --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,22 +10,16 @@ Type: `(string | { from: string; to: string })[]` Sets a list of directories of [static files](../../configure/integration/images-and-assets.mdx#serving-static-files-via-storybook-configuration) to be loaded by Storybook. -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - + When using Vite-based frameworks, additional directories may be copied to your build directory because of Vite's own [static asset handling](https://vite.dev/guide/assets#the-public-directory). You can set Vite's `publicDir` option to `false` to disable this behavior. + ## With configuration objects You can also use a configuration object to define the directories: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} \ No newline at end of file diff --git a/docs/api/main-config/main-config-stories.mdx b/docs/api/main-config/main-config-stories.mdx index 9555cc1e356e..ef50a26d0f06 100644 --- a/docs/api/main-config/main-config-stories.mdx +++ b/docs/api/main-config/main-config-stories.mdx @@ -1,8 +1,7 @@ --- -title: 'stories' +title: stories sidebar: order: 3 - title: stories --- (**Required**) @@ -25,16 +24,14 @@ Configures Storybook to load stories from the specified locations. The intention └── Button.stories.ts ``` -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - If you want to use a different naming convention, you can alter the glob using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features). - Keep in mind that some addons may assume Storybook's default naming convention. +If you want to use a different naming convention, you can alter the glob using the syntax supported by [picomatch](https://github.com/micromatch/picomatch#globbing-features). + +Keep in mind that some addons may assume Storybook's default naming convention. + ## With an array of globs @@ -43,24 +40,16 @@ Storybook will load stories from your project as found by this array of globs (p Stories are loaded in the order they are defined in the array. This allows you to control the order in which stories are displayed in the sidebar: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## With a configuration object Additionally, you can customize your Storybook configuration to load your stories based on a configuration object. This object is of the type `StoriesSpecifier`, defined below. For example, if you wanted to load your stories from a `packages/components` directory, you could adjust your `stories` configuration field into the following: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - When Storybook starts, it will look for any file containing the `stories` extension inside the `packages/components` directory and generate the titles for your stories. ### `StoriesSpecifier` @@ -102,13 +91,11 @@ When [auto-titling](../../configure/user-interface/sidebar-and-urls.mdx#csf-30-a ## With a custom implementation - 💡 Storybook now statically analyzes the configuration file to improve performance. Loading stories with a custom implementation may de-optimize or break this ability. + +Storybook now statically analyzes the configuration file to improve performance. Loading stories with a custom implementation may de-optimize or break this ability. + You can also adjust your Storybook configuration and implement custom logic to load your stories. For example, suppose you were working on a project that includes a particular pattern that the conventional ways of loading stories could not solve. In that case, you could adjust your configuration as follows: -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-swc.mdx b/docs/api/main-config/main-config-swc.mdx index a896e63079f3..16d245866077 100644 --- a/docs/api/main-config/main-config-swc.mdx +++ b/docs/api/main-config/main-config-swc.mdx @@ -1,8 +1,7 @@ --- -title: 'swc' +title: swc sidebar: order: 20 - title: swc --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,12 +10,8 @@ Type: `(config: swc.Options, options: Options) => swc.Options | Promise -{/* prettier-ignore-end */} - ## `SWC.Options` The options provided by [SWC](https://swc.rs/) are only applicable if you've enabled the [`@storybook/addon-webpack5-compiler-swc`](https://storybook.js.org/addons/@storybook/addon-webpack5-compiler-swc) addon. diff --git a/docs/api/main-config/main-config-tags.mdx b/docs/api/main-config/main-config-tags.mdx index d0cc7613bb4a..96bd848ddff5 100644 --- a/docs/api/main-config/main-config-tags.mdx +++ b/docs/api/main-config/main-config-tags.mdx @@ -1,8 +1,7 @@ --- -title: 'tags' +title: tags sidebar: order: 21 - title: tags --- Parent: [main.js|ts configuration](./main-config.mdx) diff --git a/docs/api/main-config/main-config-typescript.mdx b/docs/api/main-config/main-config-typescript.mdx index c23f8e693a77..af07b03a457d 100644 --- a/docs/api/main-config/main-config-typescript.mdx +++ b/docs/api/main-config/main-config-typescript.mdx @@ -1,35 +1,38 @@ --- -title: 'typescript' +title: typescript sidebar: order: 22 - title: typescript --- Parent: [main.js|ts configuration](./main-config.mdx) Type: - - ```ts - { - check?: boolean; - checkOptions?: CheckOptions; - reactDocgen?: 'react-docgen' | 'react-docgen-typescript' | false; - reactDocgenTypescriptOptions?: ReactDocgenTypescriptOptions; - skipCompiler?: boolean; - } - ``` - - - - ```ts - { - check?: boolean; - checkOptions?: CheckOptions; - skipCompiler?: boolean; - } - ``` - + + +```ts +{ + check?: boolean; + checkOptions?: CheckOptions; + reactDocgen?: 'react-docgen' | 'react-docgen-typescript' | false; + reactDocgenTypescriptOptions?: ReactDocgenTypescriptOptions; + skipCompiler?: boolean; +} +``` + + + + + +```ts +{ + check?: boolean; + checkOptions?: CheckOptions; + skipCompiler?: boolean; +} +``` + + Configures how Storybook handles [TypeScript files](../../configure/integration/typescript.mdx). @@ -39,54 +42,40 @@ Type: `boolean` Optionally run [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin). Note that because this uses a Webpack plugin, it is only available when using the [Webpack builder](../../builders/webpack.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `checkOptions` Type: `CheckOptions` Options to pass to `fork-ts-checker-webpack-plugin`, if [enabled](#check). See [docs for available options](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin/blob/v4.1.6/README.md#options). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - - - ## `reactDocgen` - - Type: `'react-docgen' | 'react-docgen-typescript' | false` + - Default: +## `reactDocgen` - * `false`: if `@storybook/react` is not installed - * `'react-docgen'`: if `@storybook/react` is installed +Type: `'react-docgen' | 'react-docgen-typescript' | false` - Configures which library, if any, Storybook uses to parse React components, [react-docgen](https://github.com/reactjs/react-docgen) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript). Set to `false` to disable parsing React components. `react-docgen-typescript` invokes the TypeScript compiler, which makes it slow but generally accurate. `react-docgen` performs its own analysis, which is much faster but incomplete. +Default: - {/* prettier-ignore-start */} +- `false`: if `@storybook/react` is not installed +- `'react-docgen'`: if `@storybook/react` is installed - +Configures which library, if any, Storybook uses to parse React components, [react-docgen](https://github.com/reactjs/react-docgen) or [react-docgen-typescript](https://github.com/styleguidist/react-docgen-typescript). Set to `false` to disable parsing React components. `react-docgen-typescript` invokes the TypeScript compiler, which makes it slow but generally accurate. `react-docgen` performs its own analysis, which is much faster but incomplete. - {/* prettier-ignore-end */} + - ## `reactDocgenTypescriptOptions` +## `reactDocgenTypescriptOptions` - Type: `ReactDocgenTypescriptOptions` +Type: `ReactDocgenTypescriptOptions` - Configures the options to pass to `react-docgen-typescript-plugin` if `react-docgen-typescript` is enabled. See docs for available options [for Webpack projects](https://github.com/hipstersmoothie/react-docgen-typescript-plugin) or [for Vite projects](https://github.com/joshwooding/vite-plugin-react-docgen-typescript). +Configures the options to pass to `react-docgen-typescript-plugin` if `react-docgen-typescript` is enabled. See docs for available options [for Webpack projects](https://github.com/hipstersmoothie/react-docgen-typescript-plugin) or [for Vite projects](https://github.com/joshwooding/vite-plugin-react-docgen-typescript). - {/* prettier-ignore-start */} + - - - {/* prettier-ignore-end */} - + ## `skipCompiler` @@ -94,8 +83,4 @@ Type: `boolean` Disable parsing of TypeScript files through the compiler, which is used for Webpack5. -{/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} diff --git a/docs/api/main-config/main-config-vite-final.mdx b/docs/api/main-config/main-config-vite-final.mdx index c0761375db83..1169f59e895d 100644 --- a/docs/api/main-config/main-config-vite-final.mdx +++ b/docs/api/main-config/main-config-vite-final.mdx @@ -1,8 +1,7 @@ --- -title: 'viteFinal' +title: viteFinal sidebar: order: 23 - title: viteFinal --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,12 +10,8 @@ Type: `(config: Vite.InlineConfig, options: Options) => Vite.InlineConfig | Prom Customize Storybook's Vite setup when using the [Vite builder](../../builders/vite.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `Options` Type: `{ configType?: 'DEVELOPMENT' | 'PRODUCTION' }` diff --git a/docs/api/main-config/main-config-webpack-final.mdx b/docs/api/main-config/main-config-webpack-final.mdx index 07139fbd8dc9..360f90afd0b1 100644 --- a/docs/api/main-config/main-config-webpack-final.mdx +++ b/docs/api/main-config/main-config-webpack-final.mdx @@ -1,8 +1,7 @@ --- -title: 'webpackFinal' +title: webpackFinal sidebar: order: 24 - title: webpackFinal --- Parent: [main.js|ts configuration](./main-config.mdx) @@ -11,12 +10,8 @@ Type: `async (config: Config, options: WebpackOptions) => Config` Customize Storybook's Webpack setup when using the [webpack builder](../../builders/webpack.mdx). -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## `Options` Type: `{ configType?: 'DEVELOPMENT' | 'PRODUCTION' }` diff --git a/docs/api/main-config/main-config.mdx b/docs/api/main-config/main-config.mdx index bdcd243df931..a6e550a7ebf9 100644 --- a/docs/api/main-config/main-config.mdx +++ b/docs/api/main-config/main-config.mdx @@ -1,5 +1,5 @@ --- -title: 'Main configuration' +title: Main configuration sidebar: order: 1 title: Overview @@ -7,7 +7,6 @@ sidebar: The main configuration defines a Storybook project's behavior, including the location of stories, addons to use, feature flags, and other project-specific settings. - ## The main configuration file: `main.js` or `main.ts` @@ -20,36 +19,32 @@ This configuration is defined in `.storybook/main.js|ts`, which is located relat A typical Storybook configuration file looks like this: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - ## config An object to configure Storybook containing the following properties: -* [`framework`](./main-config-framework.mdx) (Required) -* [`stories`](./main-config-stories.mdx) (Required) -* [`addons`](./main-config-addons.mdx) -* [`babel`](./main-config-babel.mdx) -* [`babelDefault`](./main-config-babel-default.mdx) -* [`build`](./main-config-build.mdx) -* [`core`](./main-config-core.mdx) -* [`docs`](./main-config-docs.mdx) -* [`env`](./main-config-env.mdx) -* [`features`](./main-config-features.mdx) -* [`indexers`](./main-config-indexers.mdx) (⚠️ Experimental) -* [`logLevel`](./main-config-log-level.mdx) -* [`managerHead`](./main-config-manager-head.mdx) -* [`previewAnnotations`](./main-config-preview-annotations.mdx) -* [`previewBody`](./main-config-preview-body.mdx) -* [`previewHead`](./main-config-preview-head.mdx) -* [`refs`](./main-config-refs.mdx) -* [`staticDirs`](./main-config-static-dirs.mdx) -* [`swc`](./main-config-swc.mdx) -* [`tags`](./main-config-tags.mdx) -* [`typescript`](./main-config-typescript.mdx) -* [`viteFinal`](./main-config-vite-final.mdx) -* [`webpackFinal`](./main-config-webpack-final.mdx) +- [`framework`](./main-config-framework.mdx) (Required) +- [`stories`](./main-config-stories.mdx) (Required) +- [`addons`](./main-config-addons.mdx) +- [`babel`](./main-config-babel.mdx) +- [`babelDefault`](./main-config-babel-default.mdx) +- [`build`](./main-config-build.mdx) +- [`core`](./main-config-core.mdx) +- [`docs`](./main-config-docs.mdx) +- [`env`](./main-config-env.mdx) +- [`features`](./main-config-features.mdx) +- [`indexers`](./main-config-indexers.mdx) (⚠️ Experimental) +- [`logLevel`](./main-config-log-level.mdx) +- [`managerHead`](./main-config-manager-head.mdx) +- [`previewAnnotations`](./main-config-preview-annotations.mdx) +- [`previewBody`](./main-config-preview-body.mdx) +- [`previewHead`](./main-config-preview-head.mdx) +- [`refs`](./main-config-refs.mdx) +- [`staticDirs`](./main-config-static-dirs.mdx) +- [`swc`](./main-config-swc.mdx) +- [`tags`](./main-config-tags.mdx) +- [`typescript`](./main-config-typescript.mdx) +- [`viteFinal`](./main-config-vite-final.mdx) +- [`webpackFinal`](./main-config-webpack-final.mdx) diff --git a/docs/api/new-frameworks.mdx b/docs/api/new-frameworks.mdx index 25809dd92f35..2f6ecf8c039c 100644 --- a/docs/api/new-frameworks.mdx +++ b/docs/api/new-frameworks.mdx @@ -1,8 +1,7 @@ --- -title: 'Frameworks' +title: Frameworks sidebar: order: 7 - title: Frameworks --- Storybook is architected to support diverse web frameworks, including React, Vue, Angular, Web Components, Svelte, and over a dozen others. This guide helps you get started on adding new framework support for Storybook. @@ -46,12 +45,8 @@ These scripts pass an `options` object to `storybook/internal/server`, a library For example, here’s the boilerplate to start the dev server with `storybook dev`: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - Thus the essence of adding framework presets is just filling in that options object. ### Server options @@ -60,24 +55,16 @@ As described above, the server `options` object does the heavy lifting of config Let’s look at the `@storybook/vue`’s options definition: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - The value of the `framework` option (i.e., ‘vue’) is something that gets passed to addons and allows them to do specific tasks related to your framework. The essence of this file is the framework presets, and these are standard [Storybook presets](../addons/writing-presets.mdx) -- you can look at framework packages in the Storybook monorepo (e.g. [React](https://github.com/storybookjs/storybook/blob/next/code/frameworks/react-vite/src/preset.ts), [Vue](https://github.com/storybookjs/storybook/blob/next/code/frameworks/vue3-vite/src/preset.ts), [Web Components](https://github.com/storybookjs/storybook/blob/next/code/frameworks/web-components-vite/src/preset.ts)) to see examples of framework-specific customizations. While developing your custom framework, not maintained by Storybook, you can specify the path to the location file with the `frameworkPath` key: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - You can add a relative path to `frameworkPath`. Don't forget that they resolve from the Storybook configuration directory (i.e., `.storybook`) by default. Make sure the `frameworkPath` ends up at the `dist/client/index.js` file within your framework app. @@ -92,52 +79,32 @@ Storybook stories are ES6 objects that return a “renderable object.” Consider the following React story: -{/* prettier-ignore-start */} - -{/* prettier-ignore-end */} - In this case, the renderable object is the React element, `