diff --git a/docs/addons/addon-knowledge-base.mdx b/docs/addons/addon-knowledge-base.mdx index 9710f02ad65c..cf98755e930b 100644 --- a/docs/addons/addon-knowledge-base.mdx +++ b/docs/addons/addon-knowledge-base.mdx @@ -12,11 +12,7 @@ To make that possible, you need to pass the `paramKey` element when you register {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -24,15 +20,7 @@ Then when adding a story, you can pass a disabled parameter. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -47,9 +35,9 @@ 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/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. @@ -79,9 +67,7 @@ Complementing the components, also included is a set of UI primitives. Use the c | Typography | [See implementation](https://github.com/storybookjs/storybook/tree/master/code/ui/components/src/typography) | [See story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-typography--all) | - -The color palette implemented by `@storybook/components` is a high-level abstraction of the [`@storybook/theming`](https://github.com/storybookjs/storybook/tree/next/code/lib/theming/src) package. - + The color palette implemented by `@storybook/components` is a high-level abstraction of the [`@storybook/theming`](https://github.com/storybookjs/storybook/tree/next/code/lib/theming/src) package. ### Build system @@ -97,9 +83,7 @@ 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 @@ -128,11 +112,7 @@ If you're working on a preset that loads third-party addons, which you don't hav {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/addons/addon-migration-guide.mdx b/docs/addons/addon-migration-guide.mdx index 13d1a2d3a263..decd58d446b0 100644 --- a/docs/addons/addon-migration-guide.mdx +++ b/docs/addons/addon-migration-guide.mdx @@ -5,9 +5,7 @@ title: Addon migration guide for Storybook 8.0 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 8.0, bringing new features and improvements, this guide is here to assist you in migrating your addons from 7.x to 8.0. If you need to migrate your addon from an earlier version of Storybook, please first refer to the [Addon migration guide for Storybook 7.0](https://storybook.js.org/docs/7.6/addons/addon-migration-guide). - -As we gather feedback from the community, we’ll update this page. We also have a general [Storybook migration guide](../migration-guide.md) if you’re looking for that. - + As we gather feedback from the community, we’ll update this page. We also have a general [Storybook migration guide](../migration-guide.md) if you’re looking for that. ## Updating dependencies @@ -44,9 +42,7 @@ To remove your addon's peer dependency on React and reduce its install size, do For an example, see [the updates we've made to the Addon Kit](https://github.com/storybookjs/addon-kit/compare/79282986..fa7ee7c). These changes are optional but recommended. - -This assumes your addon uses [tsup](https://tsup.egoist.dev/) for bundling. If your addon was built with an older version of the Addon Kit that uses Babel for bundling, you must first switch to tsup. For guidance, explore these older changes implemented in the Addon Kit [repository](https://github.com/storybookjs/addon-kit/pull/45/files). - + This assumes your addon uses [tsup](https://tsup.egoist.dev/) for bundling. If your addon was built with an older version of the Addon Kit that uses Babel for bundling, you must first switch to tsup. For guidance, explore these older changes implemented in the Addon Kit [repository](https://github.com/storybookjs/addon-kit/pull/45/files). ### @storybook/components deprecations @@ -71,13 +67,7 @@ As a workaround, update your documentation to tell users to opt-in to Babel supp {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -85,14 +75,12 @@ As a workaround, update your documentation to tell users to opt-in to Babel supp The Addon Kit [repository](https://github.com/storybookjs/addon-kit) has already been updated to support Storybook 8.0, and you can use it as a reference for your migration. You'll see the changes mentioned in this guide, including ESM support via the `type: module` configuration. As an addon maintainer, we encourage you to update your addon to include them. It simplifies the setup and makes it easier for users to use your addon with the latest version of Storybook. If you choose to follow along with the ESM migration, we've prepared an abbreviated list of changes below. -- [`package.json`](https://github.com/storybookjs/addon-kit/compare/79282986..fa7ee7c#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519) for dependency management, ESM support and updates to the addon's entry points. -- [`tsup.config.ts`](https://github.com/storybookjs/addon-kit/compare/79282986..fa7ee7c#diff-8fed899bdbc24789a7bb4973574e624ed6207c6ce572338bc3c3e117672b2a2) for bundling changes, factoring in Storybook's globals. -- [`.storybook/local-preset.js`](https://github.com/storybookjs/addon-kit/compare/79282986..fa7ee7c#diff-390b53ea479b1ceffcbf31944f644ee23aa9f337b75a8a0ffd815bed50d376cb) to support the ESM migration. +* [`package.json`](https://github.com/storybookjs/addon-kit/compare/79282986..fa7ee7c#diff-7ae45ad102eab3b6d7e7896acd08c427a9b25b346470d7bc6507b6481575d519) for dependency management, ESM support and updates to the addon's entry points. +* [`tsup.config.ts`](https://github.com/storybookjs/addon-kit/compare/79282986..fa7ee7c#diff-8fed899bdbc24789a7bb4973574e624ed6207c6ce572338bc3c3e117672b2a2) for bundling changes, factoring in Storybook's globals. +* [`.storybook/local-preset.js`](https://github.com/storybookjs/addon-kit/compare/79282986..fa7ee7c#diff-390b53ea479b1ceffcbf31944f644ee23aa9f337b75a8a0ffd815bed50d376cb) to support the ESM migration. - -For a complete overview of the changes applied to the Addon Kit to fully support Storybook 8.0, see the following [diff view](https://github.com/storybookjs/addon-kit/compare/79282986..fa7ee7c). - + For a complete overview of the changes applied to the Addon Kit to fully support Storybook 8.0, see the following [diff view](https://github.com/storybookjs/addon-kit/compare/79282986..fa7ee7c). ## Releasing diff --git a/docs/addons/addon-types.mdx b/docs/addons/addon-types.mdx index 71c5415769ac..5fe1f587115b 100644 --- a/docs/addons/addon-types.mdx +++ b/docs/addons/addon-types.mdx @@ -18,11 +18,7 @@ Use this boilerplate code to add a new `Panel` to Storybook's UI: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -36,22 +32,16 @@ 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.md#conditionally-render-the-addon). -The `match` property allows you to conditionally render your toolbar addon, [based on the current view](./writing-addons.md#conditionally-render-the-addon). - -
- -The `icon` element used in the example loads the icons from the `@storybook/components` package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. +
+ The `icon` element used in the example loads the icons from the `@storybook/components` package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. ### Tabs @@ -64,18 +54,12 @@ 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.md). - + Learn how to write your own addon that includes these UI elements [here](./writing-addons.md). ## Preset addons @@ -86,18 +70,14 @@ 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.md) for the basics of addon development -- [Presets](./writing-presets.md) for preset development -- [Integration catalog](./integration-catalog.md) for requirements and available recipes -- [API reference](./addons-api.md) to learn about the available APIs +* Types of addons for other types of addons +* [Writing addons](./writing-addons.md) for the basics of addon development +* [Presets](./writing-presets.md) for preset development +* [Integration catalog](./integration-catalog.md) for requirements and available recipes +* [API reference](./addons-api.md) to learn about the available APIs diff --git a/docs/addons/addons-api.mdx b/docs/addons/addons-api.mdx index 814a71792c86..a8e1b9fa47f6 100644 --- a/docs/addons/addons-api.mdx +++ b/docs/addons/addons-api.mdx @@ -8,16 +8,12 @@ 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. +* `@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 */} - + {/* prettier-ignore-end */} @@ -25,24 +21,18 @@ Our API is exposed via two distinct packages, each one with a different purpose: 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. +* `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 */} - + {/* 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() @@ -51,11 +41,7 @@ Serves as the entry point for all addons. It allows you to register an addon and {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -69,11 +55,7 @@ It has a NodeJS [EventEmitter](https://nodejs.org/api/events.html) compatible AP {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -83,28 +65,22 @@ Use the `makeDecorator` API to create decorators in the style of the official ad {/* 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.md) or [parameters](../writing-stories/parameters.md). -- `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.md) or [parameters](../writing-stories/parameters.md). +* `wrapper`: your decorator function. Takes the `getStory`, `context`, and both the `options` and `parameters` (as defined in `skipIfNoParametersOrOptions` above). ---- +*** ## Storybook API @@ -116,21 +92,7 @@ The `selectStory` API method allows you to select a single story. It accepts the {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -138,11 +100,7 @@ This is how you can select the above story: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -152,11 +110,7 @@ Similar to the `selectStory` API method, but it only accepts the story as the on {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -166,11 +120,7 @@ This method allows you to set query string parameters. You can use that as tempo {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -178,11 +128,7 @@ Additionally, if you need to remove a query parameter, set it as `null` instead {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -192,11 +138,7 @@ Allows retrieval of a query parameter enabled via the `setQueryParams` API metho {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -206,11 +148,7 @@ This method allows you to get the application URL state, including any overridde {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -220,11 +158,7 @@ This method allows you to register a handler function called whenever the user n {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -234,11 +168,7 @@ This method allows you to override the default Storybook UI configuration (e.g., {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -272,7 +202,7 @@ The following options are configurable under the `toolbar` namespace: | ------ | ------ | ---------------------------------- | ------------------- | | **id** | String | Toggle visibility for toolbar item | `{ hidden: false }` | ---- +*** ## Storybook hooks @@ -284,11 +214,7 @@ It allows access to Storybook's internal state. Similar to the [`useglobals`](#u {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -298,11 +224,7 @@ The `useStorybookApi` hook is a convenient helper to allow you full access to th {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -314,11 +236,7 @@ The messages can be listened to on both the iframe and the manager. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -328,11 +246,7 @@ The `useAddonState` is a useful hook for addons that require data persistence, e {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -342,11 +256,7 @@ The `useParameter` retrieves the current story's parameters. If the parameter's {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -356,11 +266,7 @@ Extremely useful hook for addons that rely on Storybook [Globals](../essentials/ {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -370,18 +276,14 @@ Hook that allows you to retrieve or update a story's [`args`](../writing-stories {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} **Learn more about the Storybook addon ecosystem** -- [Types of addons](./addon-types.md) for other types of addons -- [Writing addons](./writing-addons.md) for the basics of addon development -- [Presets](./writing-presets.md) for preset development -- [Integration catalog](./integration-catalog.md) for requirements and available recipes -- API reference to learn about the available APIs +* [Types of addons](./addon-types.md) for other types of addons +* [Writing addons](./writing-addons.md) for the basics of addon development +* [Presets](./writing-presets.md) for preset development +* [Integration catalog](./integration-catalog.md) 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 c92faf125d01..d76ec3a04f0c 100644 --- a/docs/addons/configure-addons.mdx +++ b/docs/addons/configure-addons.mdx @@ -8,7 +8,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 just 1 line of config! For more on presets, see: [Write a preset addon](./writing-presets.md) diff --git a/docs/addons/index.mdx b/docs/addons/index.mdx index 349090fb5f80..dade7e7e26f9 100644 --- a/docs/addons/index.mdx +++ b/docs/addons/index.mdx @@ -14,10 +14,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 4c85c98643f4..bc994b929441 100644 --- a/docs/addons/install-addons.mdx +++ b/docs/addons/install-addons.mdx @@ -12,20 +12,12 @@ Run the `storybook add` command using your chosen package manager, and the CLI w {/* 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 @@ -36,13 +28,7 @@ Run the following command with your package manager of choice to install the add {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -50,12 +36,7 @@ Next, update `.storybook/main.js|ts` to the following: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -69,12 +50,6 @@ To remove an addon from Storybook, you can choose to manually uninstall it and r {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/addons/integration-catalog.mdx b/docs/addons/integration-catalog.mdx index e5620b1a7c50..8828973cfc5c 100644 --- a/docs/addons/integration-catalog.mdx +++ b/docs/addons/integration-catalog.mdx @@ -10,15 +10,13 @@ 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.md#get-started) 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.md#get-started) 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.md). - + Get a refresher on how to [write a Storybook addon](./writing-addons.md). ### Addon metadata @@ -44,20 +42,18 @@ Customize your addon's appearance by adding the `storybook` property with the fo Use the list below as a reference when filling in the values for both the `supportedFrameworks` and `unsupportedFrameworks` fields. -- react -- vue -- angular -- web-components -- ember -- html -- svelte -- preact -- react-native +* react +* vue +* angular +* web-components +* ember +* html +* svelte +* preact +* react-native - -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 @@ -106,8 +102,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.md) for other types of addons -- [Writing addons](./writing-addons.md) for the basics of addon development -- [Presets](./writing-presets.md) for preset development -- Integration catalog for requirements and available recipes -- [API reference](./addons-api.md) to learn about the available APIs +* [Types of addons](./addon-types.md) for other types of addons +* [Writing addons](./writing-addons.md) for the basics of addon development +* [Presets](./writing-presets.md) for preset development +* Integration catalog for requirements and available recipes +* [API reference](./addons-api.md) to learn about the available APIs diff --git a/docs/addons/writing-addons.mdx b/docs/addons/writing-addons.mdx index cc08f6200b63..e8cc44b2adc9 100644 --- a/docs/addons/writing-addons.mdx +++ b/docs/addons/writing-addons.mdx @@ -9,18 +9,15 @@ Storybook addons are a powerful way to extend Storybook's functionality and cust This reference guide is to help you develop a mental model for how Storybook addons work by building a simple addon based on the popular [Outline addon](https://storybook.js.org/addons/@storybook/addon-outline/). Throughout this guide, you'll learn how addons are structured, Storybook's APIs, how to test your addon locally, and how to publish it. ## Addon anatomy There are two main categories of addons, each with its role: -- **UI-based**: These addons are responsible for customizing the interface, enabling shortcuts for common tasks, or displaying additional information in the UI. -- **Presets**: [These](./writing-presets.md) are pre-configured settings or configurations that enable developers to quickly set up and customize their environment with a specific set of features, functionality, or technology. +* **UI-based**: These addons are responsible for customizing the interface, enabling shortcuts for common tasks, or displaying additional information in the UI. +* **Presets**: [These](./writing-presets.md) are pre-configured settings or configurations that enable developers to quickly set up and customize their environment with a specific set of features, functionality, or technology. ### UI-based addons @@ -28,13 +25,7 @@ The addon built in this guide is a UI-based addon, specifically a [toolbar](./ad {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -43,30 +34,19 @@ The addon built in this guide is a UI-based addon, specifically a [toolbar](./ad To create your first addon, you're going to use the [Addon Kit](https://github.com/storybookjs/addon-kit), a ready-to-use template featuring all the required building blocks, dependencies and configurations to help you get started building your addon. In the Addon Kit repository, click the **Use this template** button to create a new repository based on the Addon Kit's code. 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 @@ -83,11 +63,7 @@ By default, code for the UI-based addons is located in one of the following file {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -144,11 +120,7 @@ Moving onto the manager, here we register the addon with Storybook using a uniqu {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -156,10 +128,10 @@ Moving onto the manager, here we register the addon with Storybook using a uniqu 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.md#tabs)) where the toolbar addon is visible. For example: -- `({ tabId }) => tabId === 'my-addon/tab'` will show your addon when viewing the tab with the ID `my-addon/tab`. -- `({ viewMode }) => viewMode === 'story'` will show your addon when viewing a story in the canvas. -- `({ viewMode }) => viewMode === 'docs'` will show your addon when viewing the documentation for a component. -- `({ tabId, viewMode }) => !tabId && viewMode === 'story'` will show your addon when viewing a story in the canvas and not in a custom tab (i.e. when `tabId === undefined`). +* `({ tabId }) => tabId === 'my-addon/tab'` will show your addon when viewing the tab with the ID `my-addon/tab`. +* `({ viewMode }) => viewMode === 'story'` will show your addon when viewing a story in the canvas. +* `({ viewMode }) => viewMode === 'docs'` will show your addon when viewing the documentation for a component. +* `({ tabId, viewMode }) => !tabId && viewMode === 'story'` will show your addon when viewing a story in the canvas and not in a custom tab (i.e. when `tabId === undefined`). Run the `start` script to build and start Storybook and verify that the addon is registered correctly and showing in the UI. @@ -171,11 +143,7 @@ In Storybook, applying styles for addons is considered a side-effect. Therefore, {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -183,11 +151,7 @@ Next, create the file with the styles we want to inject with the following conte {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -195,11 +159,7 @@ Since the addon can be active in both the story and documentation modes, the DOM {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -209,8 +169,8 @@ Storybook addons, similar to most packages in the JavaScript ecosystem, are dist 1. Have a `dist` folder with the transpiled code. 2. A `package.json` file declaring: - - Module-related information - - Integration catalog metadata + * Module-related information + * Integration catalog metadata ### Module Metadata @@ -270,9 +230,7 @@ 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.md). - + 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.md). One essential item to note is the `keywords` property as it maps to the catalog's tag system. Adding the `storybook-addons` 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. @@ -301,13 +259,7 @@ Finally, run the following command to create a release for your addon. This will {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -321,8 +273,8 @@ Then, click the **New repository secret**, name it `NPM_TOKEN`, and paste the to **Learn more about the Storybook addon ecosystem** -- [Types of addons](./addon-types.md) for other types of addons -- Writing addons for the basics of addon development -- [Presets](./writing-presets.md) for preset development -- [Integration catalog](./integration-catalog.md) for requirements and available recipes -- [API reference](./addons-api.md) to learn about the available APIs +* [Types of addons](./addon-types.md) for other types of addons +* Writing addons for the basics of addon development +* [Presets](./writing-presets.md) for preset development +* [Integration catalog](./integration-catalog.md) for requirements and available recipes +* [API reference](./addons-api.md) to learn about the available APIs diff --git a/docs/addons/writing-presets.mdx b/docs/addons/writing-presets.mdx index 34511afba39e..48278ee538ac 100644 --- a/docs/addons/writing-presets.mdx +++ b/docs/addons/writing-presets.mdx @@ -14,12 +14,7 @@ This type of preset allows you to encapsulate and organize configurations specif {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -29,11 +24,7 @@ This type of preset is user-facing and responsible for registering the addon wit {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -47,19 +38,12 @@ To customize Storybook's Babel configuration and add support for additional feat {/* 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 @@ -72,12 +56,7 @@ If you are creating a preset and want to include Vite support, the `viteFinal` A {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -87,12 +66,7 @@ To customize the Webpack configuration in Storybook to add support for additiona {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -102,11 +76,7 @@ If you're writing a preset that loads third-party addons, which you may not have {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -116,14 +86,7 @@ If you need additional settings to render stories for a preset, like [decorators {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -133,12 +96,7 @@ The presets API is designed to be flexible and allow you to customize Storybook {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -148,12 +106,7 @@ For addon consumers, the [`managerEntries`](#managerentries) API can be too tech {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -169,14 +122,7 @@ The Storybook preset API also provides access to the UI configuration, including {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -184,12 +130,7 @@ Additionally, if you need to customize the manager (i.e., where Storybook’s se {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -203,8 +144,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.md) for other types of addons -- [Writing addons](./writing-addons.md) for the basics of addon development -- Presets for preset development -- [Integration catalog](./integration-catalog.md) for requirements and available recipes -- [API reference](./addons-api.md) to learn about the available APIs +* [Types of addons](./addon-types.md) for other types of addons +* [Writing addons](./writing-addons.md) for the basics of addon development +* Presets for preset development +* [Integration catalog](./integration-catalog.md) for requirements and available recipes +* [API reference](./addons-api.md) to learn about the available APIs diff --git a/docs/api/arg-types.mdx b/docs/api/arg-types.mdx index 47744ac8b37e..71fc66d403ad 100644 --- a/docs/api/arg-types.mdx +++ b/docs/api/arg-types.mdx @@ -34,15 +34,7 @@ ArgTypes are most often specified at the meta (component) level, in the [default {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -50,12 +42,7 @@ They can apply to all stories when specified at the project (global) level, in t {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -63,15 +50,7 @@ Or they can apply only to a [specific story](../writing-stories/index.md#definin {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -130,15 +109,7 @@ Specify the behavior of the [controls addon](../essentials/controls.md) for the {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -150,28 +121,26 @@ Default: [Inferred](#automatic-argtype-inference); `'select'`, if [`options`](#o Specifies the type of control used to change the arg value with the [controls addon](../essentials/controls.md). Here are the available types, `ControlType`, grouped by the type of data they handle: -| Data type | ControlType | Description | +| Data type | ControlType | Description | | -------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **array** | `'object'` | Provides a JSON-based editor to handle the values of the array. Also allows editing in raw mode.
`{ control: 'object' }` | -| **boolean** | `'boolean'` | Provides a toggle for switching between possible states.
`{ control: 'boolean' }` | -| **enum** | `'check'` | Provides a set of stacked checkboxes for selecting multiple options.
`{ control: 'check', options: ['email', 'phone', 'mail'] }` | -| | `'inline-check'` | Provides a set of inlined checkboxes for selecting multiple options.
`{ control: 'inline-check', options: ['email', 'phone', 'mail'] }` | -| | `'radio'` | Provides a set of stacked radio buttons based on the available options.
`{ control: 'radio', options: ['email', 'phone', 'mail'] }` | -| | `'inline-radio'` | Provides a set of inlined radio buttons based on the available options.
`{ control: 'inline-radio', options: ['email', 'phone', 'mail'] }` | -| | `'select'` | Provides a select to choose a single value from the options.
`{ control: 'select', options: [20, 30, 40, 50] }` | -| | `'multi-select'` | Provides a select to choose multiple values from the options.
`{ control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] }` | -| **number** | `'number'` | Provides a numeric input to include the range of all possible values.
`{ control: { type: 'number', min:1, max:30, step: 2 } }` | -| | `'range'` | Provides a range slider to include all possible values.
`{ control: { type: 'range', min: 1, max: 30, step: 3 } }` | -| **object** | `'file'` | Provides a file input that returns an array of URLs. Can be further customized to accept specific file types.
`{ control: { type: 'file', accept: '.png' } }` | -| | `'object'` | Provides a JSON-based editor to handle the object's values. Also allows editing in raw mode.
`{ control: 'object' }` | -| **string** | `'color'` | Provides a color picker to choose color values. Can be additionally configured to include a set of color presets.
`{ control: { type: 'color', presetColors: ['red', 'green']} }` | +| **array** | `'object'` | Provides a JSON-based editor to handle the values of the array. Also allows editing in raw mode.
`{ control: 'object' }` | +| **boolean** | `'boolean'` | Provides a toggle for switching between possible states.
`{ control: 'boolean' }` | +| **enum** | `'check'` | Provides a set of stacked checkboxes for selecting multiple options.
`{ control: 'check', options: ['email', 'phone', 'mail'] }` | +| | `'inline-check'` | Provides a set of inlined checkboxes for selecting multiple options.
`{ control: 'inline-check', options: ['email', 'phone', 'mail'] }` | +| | `'radio'` | Provides a set of stacked radio buttons based on the available options.
`{ control: 'radio', options: ['email', 'phone', 'mail'] }` | +| | `'inline-radio'` | Provides a set of inlined radio buttons based on the available options.
`{ control: 'inline-radio', options: ['email', 'phone', 'mail'] }` | +| | `'select'` | Provides a select to choose a single value from the options.
`{ control: 'select', options: [20, 30, 40, 50] }` | +| | `'multi-select'` | Provides a select to choose multiple values from the options.
`{ control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] }` | +| **number** | `'number'` | Provides a numeric input to include the range of all possible values.
`{ control: { type: 'number', min:1, max:30, step: 2 } }` | +| | `'range'` | Provides a range slider to include all possible values.
`{ control: { type: 'range', min: 1, max: 30, step: 3 } }` | +| **object** | `'file'` | Provides a file input that returns an array of URLs. Can be further customized to accept specific file types.
`{ control: { type: 'file', accept: '.png' } }` | +| | `'object'` | Provides a JSON-based editor to handle the object's values. Also allows editing in raw mode.
`{ control: 'object' }` | +| **string** | `'color'` | Provides a color picker to choose color values. Can be additionally configured to include a set of color presets.
`{ control: { type: 'color', presetColors: ['red', 'green']} }` | | | `'date'` | Provides a datepicker to choose a date.
`{ control: 'date' }` | -| | `'text'` | Provides a freeform text input.
`{ control: 'text' }` | +| | `'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` @@ -220,15 +189,7 @@ Describe the arg. (If you intend to describe the type of the arg, you should use {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -250,15 +211,7 @@ Conditionally render an argType based on the value of another [arg](../writing-s {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -274,15 +227,7 @@ When dealing with non-primitive values, you'll notice that you'll run into some {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -294,24 +239,14 @@ The `argTypes` object uses the name of the arg as the key. By default, that key {/* 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). - + 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). ### `options` @@ -324,15 +259,7 @@ If the arg accepts a finite set of values, you can specify them with `options`. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -362,15 +289,7 @@ Specify how the arg is documented in the [`ArgTypes` doc block](./doc-block-argt {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -406,7 +325,7 @@ Set to `true` to indicate that the argType is read-only. Type: `string` -Display the argType under a subcategory heading (which displays under the [`category`] heading), with the label specified by `subcategory`. +Display the argType under a subcategory heading (which displays under the \[`category`] heading), with the label specified by `subcategory`. #### `table.type` @@ -425,53 +344,52 @@ Type: `'boolean' | 'function' | 'number' | 'string' | 'symbol' | SBType` The full type of `SBType` is:
-SBType + SBType -```ts -interface SBBaseType { - required?: boolean; - raw?: string; -} + ```ts + interface SBBaseType { + required?: boolean; + raw?: string; + } -type SBScalarType = SBBaseType & { - name: 'boolean' | 'string' | 'number' | 'function' | 'symbol'; -}; - -type SBArrayType = SBBaseType & { - name: 'array'; - value: SBType; -}; -type SBObjectType = SBBaseType & { - name: 'object'; - value: Record; -}; -type SBEnumType = SBBaseType & { - name: 'enum'; - value: (string | number)[]; -}; -type SBIntersectionType = SBBaseType & { - name: 'intersection'; - value: SBType[]; -}; -type SBUnionType = SBBaseType & { - name: 'union'; - value: SBType[]; -}; -type SBOtherType = SBBaseType & { - name: 'other'; - value: string; -}; - -type SBType = - | SBScalarType - | SBEnumType - | SBArrayType - | SBObjectType - | SBIntersectionType - | SBUnionType - | SBOtherType; -``` + type SBScalarType = SBBaseType & { + name: 'boolean' | 'string' | 'number' | 'function' | 'symbol'; + }; + + type SBArrayType = SBBaseType & { + name: 'array'; + value: SBType; + }; + type SBObjectType = SBBaseType & { + name: 'object'; + value: Record; + }; + type SBEnumType = SBBaseType & { + name: 'enum'; + value: (string | number)[]; + }; + type SBIntersectionType = SBBaseType & { + name: 'intersection'; + value: SBType[]; + }; + type SBUnionType = SBBaseType & { + name: 'union'; + value: SBType[]; + }; + type SBOtherType = SBBaseType & { + name: 'other'; + value: string; + }; + type SBType = + | SBScalarType + | SBEnumType + | SBArrayType + | SBObjectType + | SBIntersectionType + | SBUnionType + | SBOtherType; + ```
Default: [Inferred](#automatic-argtype-inference) @@ -482,15 +400,7 @@ If you only need to specify the documented type, you should use [`table.type`](# {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -504,14 +414,6 @@ Define the default value of the argType. Deprecated in favor of defining the [`a {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/cli-options.mdx b/docs/api/cli-options.mdx index ae2cb3d779f1..392c5f0ef99a 100644 --- a/docs/api/cli-options.mdx +++ b/docs/api/cli-options.mdx @@ -6,9 +6,7 @@ hideRendererSelector: true 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.md#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.md#how-to-opt-out) if you'd not like to share any information. ## API commands @@ -16,9 +14,7 @@ Storybook collects completely anonymous data to help us improve user experience. 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` @@ -33,36 +29,34 @@ Options include: | Option | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `--help` | Output usage information
`storybook dev --help` | -| `-V`, `--version` | Output the version number
`storybook dev -V` | -| `-p`, `--port [number]` | Port to run Storybook
`storybook dev -p 9009` | -| `--exact-port [number]` | 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 --exact-port 9009` | -| `-h`, `--host [string]` | Host to run Storybook
`storybook dev -h my-host.com` | -| `-c`, `--config-dir [dir-name]` | Directory where to load Storybook configurations from
`storybook dev -c .storybook` | -| `--loglevel [level]` | Controls level of logging during build.
Available options: `silly`, `verbose`, `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` | -| `--ssl-key` | Provide an SSL key. (Required with --https)
`storybook dev --ssl-key my-ssl-key` | -| `--smoke-test` | Exit after successful start
`storybook dev --smoke-test` | -| `--ci` | CI mode (skip interactive prompts, don't open browser)
`storybook dev --ci` | -| `--no-open` | Do not open Storybook automatically in the browser
`storybook dev --no-open` | -| `--quiet` | Suppress verbose build output
`storybook dev --quiet` | -| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook dev --debug` | -| `--debug-webpack` | Display final webpack configurations for debugging purposes
`storybook dev --debug-webpack` | -| `--stats-json [dir-name]` | Write stats JSON to disk
Requires Webpack
`storybook dev --stats-json /tmp/stats` | -| `--no-version-updates` | Skips Storybook's update check
`storybook dev --no-version-updates` | -| `--docs` | Starts Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#preview-storybooks-documentation)
`storybook dev --docs` | -| `--initial-path [path]` | Configures the URL Storybook should open when it opens the browser for the first time
`storybook dev --initial-path=/docs/getting-started--docs` | -| `--preview-url [path]` | Overrides the default Storybook preview with a custom built preview URL
`storybook dev --preview-url=http://localhost:1337/external-iframe.html` | -| `--force-build-preview` | Forcefully builds Storybook's preview iframe.
Useful if you're experiencing issues, or combined with `--preview-url` to ensure the preview is up-to-date
`storybook dev --force-build-preview` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook dev --disable-telemetry` | -| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook dev --enable-crash-reports` | +| `--help` | Output usage information
`storybook dev --help` | +| `-V`, `--version` | Output the version number
`storybook dev -V` | +| `-p`, `--port [number]` | Port to run Storybook
`storybook dev -p 9009` | +| `--exact-port [number]` | 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 --exact-port 9009` | +| `-h`, `--host [string]` | Host to run Storybook
`storybook dev -h my-host.com` | +| `-c`, `--config-dir [dir-name]` | Directory where to load Storybook configurations from
`storybook dev -c .storybook` | +| `--loglevel [level]` | Controls level of logging during build.
Available options: `silly`, `verbose`, `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` | +| `--ssl-key` | Provide an SSL key. (Required with --https)
`storybook dev --ssl-key my-ssl-key` | +| `--smoke-test` | Exit after successful start
`storybook dev --smoke-test` | +| `--ci` | CI mode (skip interactive prompts, don't open browser)
`storybook dev --ci` | +| `--no-open` | Do not open Storybook automatically in the browser
`storybook dev --no-open` | +| `--quiet` | Suppress verbose build output
`storybook dev --quiet` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook dev --debug` | +| `--debug-webpack` | Display final webpack configurations for debugging purposes
`storybook dev --debug-webpack` | +| `--stats-json [dir-name]` | Write stats JSON to disk
Requires Webpack
`storybook dev --stats-json /tmp/stats` | +| `--no-version-updates` | Skips Storybook's update check
`storybook dev --no-version-updates` | +| `--docs` | Starts Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#preview-storybooks-documentation)
`storybook dev --docs` | +| `--initial-path [path]` | Configures the URL Storybook should open when it opens the browser for the first time
`storybook dev --initial-path=/docs/getting-started--docs` | +| `--preview-url [path]` | Overrides the default Storybook preview with a custom built preview URL
`storybook dev --preview-url=http://localhost:1337/external-iframe.html` | +| `--force-build-preview` | Forcefully builds Storybook's preview iframe.
Useful if you're experiencing issues, or combined with `--preview-url` to ensure the preview is up-to-date
`storybook dev --force-build-preview` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook dev --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook dev --enable-crash-reports` | - -With the release of Storybook 8, the `-s` CLI flag was removed. We recommend using the [static directory](../configure/images-and-assets.md#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/images-and-assets.md#serving-static-files-via-storybook) instead if you need to serve static files. ### `build` @@ -77,21 +71,21 @@ Options include: | Option | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook build --help` | -| `-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]` | Directory where to load Storybook configurations from
`storybook build -c .storybook` | -| `--loglevel [level]` | Controls level of logging during build.
Available options: `silly`, `verbose`, `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` | -| `--stats-json [dir-name]` | Write stats JSON to disk
Requires Webpack
`storybook build --stats-json /tmp/stats` | -| `--docs` | Builds Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#publish-storybooks-documentation)
`storybook build --docs` | -| `--test` | Optimize Storybook's production build for performance and tests by removing unnecessary features with the `test` option. Learn more [here](../api/main-config-build.md).
`storybook build --test` | -| `--preview-url [path]` | Overrides the default Storybook preview with a custom built preview URL
`storybook build --preview-url=http://localhost:1337/external-iframe.html` | -| `--force-build-preview` | Forcefully builds Storybook's preview iframe.
Useful if you're experiencing issues, or combined with `--preview-url` to ensure the preview is up-to-date
`storybook build --force-build-preview` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook build --disable-telemetry` | -| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook build --enable-crash-reports` | +| `-h`, `--help` | Output usage information
`storybook build --help` | +| `-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]` | Directory where to load Storybook configurations from
`storybook build -c .storybook` | +| `--loglevel [level]` | Controls level of logging during build.
Available options: `silly`, `verbose`, `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` | +| `--stats-json [dir-name]` | Write stats JSON to disk
Requires Webpack
`storybook build --stats-json /tmp/stats` | +| `--docs` | Builds Storybook in documentation mode. Learn more about it in [here](../writing-docs/build-documentation.md#publish-storybooks-documentation)
`storybook build --docs` | +| `--test` | Optimize Storybook's production build for performance and tests by removing unnecessary features with the `test` option. Learn more [here](../api/main-config-build.md).
`storybook build --test` | +| `--preview-url [path]` | Overrides the default Storybook preview with a custom built preview URL
`storybook build --preview-url=http://localhost:1337/external-iframe.html` | +| `--force-build-preview` | Forcefully builds Storybook's preview iframe.
Useful if you're experiencing issues, or combined with `--preview-url` to ensure the preview is up-to-date
`storybook build --force-build-preview` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook build --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook build --enable-crash-reports` | ### `init` @@ -107,19 +101,19 @@ Options include: | Option | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook init --help` | -| `-b`, `--builder` | Defines the [builder](../builders/index.md) to use for your Storybook instance
`storybook init --builder webpack5` | -| `-f`,`--force` | Forcefully installs Storybook into your project, prompting you to overwrite existing files
`storybook init --force` | -| `-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/frameworks.md) to use for your Storybook instance
`storybook init --type solid` | -| `-y`, `--yes` | Skips interactive prompts and automatically installs Storybook per specified version
`storybook init --yes` | -| `--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` | -| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook init --debug` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#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.md#crash-reports-disabled-by-default)
`storybook init --enable-crash-reports` | -| `--no-dev` | Complete the initialization of Storybook without running the Storybook dev server
`storybook init --no-dev` | +| `-h`, `--help` | Output usage information
`storybook init --help` | +| `-b`, `--builder` | Defines the [builder](../builders/index.md) to use for your Storybook instance
`storybook init --builder webpack5` | +| `-f`,`--force` | Forcefully installs Storybook into your project, prompting you to overwrite existing files
`storybook init --force` | +| `-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/frameworks.md) to use for your Storybook instance
`storybook init --type solid` | +| `-y`, `--yes` | Skips interactive prompts and automatically installs Storybook per specified version
`storybook init --yes` | +| `--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` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook init --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#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.md#crash-reports-disabled-by-default)
`storybook init --enable-crash-reports` | +| `--no-dev` | Complete the initialization of Storybook without running the Storybook dev server
`storybook init --no-dev` | ### `add` @@ -133,11 +127,11 @@ Options include: | Option | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook add --help` | -| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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` | +| `-h`, `--help` | Output usage information
`storybook add --help` | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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` | ### `remove` @@ -151,11 +145,11 @@ Options include: | Option | Description | | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook remove --help` | -| `--package-manager` | Sets the package manager to use when removing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook remove [addon]--package-manager pnpm` | -| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook remove --debug` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook remove --disable-telemetry` | -| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook remove --enable-crash-reports` | +| `-h`, `--help` | Output usage information
`storybook remove --help` | +| `--package-manager` | Sets the package manager to use when removing the addon.
Available package managers include `npm`, `yarn`, and `pnpm`
`storybook remove [addon]--package-manager pnpm` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook remove --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook remove --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook remove --enable-crash-reports` | ### `upgrade` @@ -171,16 +165,16 @@ Options include: | Option | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook upgrade --help` | -| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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.md#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.md#crash-reports-disabled-by-default)
`storybook upgrade --enable-crash-reports` | +| `-h`, `--help` | Output usage information
`storybook upgrade --help` | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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.md#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.md#crash-reports-disabled-by-default)
`storybook upgrade --enable-crash-reports` | ### `migrate` @@ -191,9 +185,7 @@ 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. @@ -202,14 +194,14 @@ Options include: | Option | Description | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook migrate --help` | -| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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` | +| `-h`, `--help` | Output usage information
`storybook migrate --help` | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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` @@ -225,17 +217,17 @@ Options include: | Option | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook automigrate --help` | -| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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.md#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.md#crash-reports-disabled-by-default)
`storybook automigrate --enable-crash-reports` | +| `-h`, `--help` | Output usage information
`storybook automigrate --help` | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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.md#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.md#crash-reports-disabled-by-default)
`storybook automigrate --enable-crash-reports` | ### `doctor` @@ -249,10 +241,10 @@ Options include: | Option | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook doctor --help` | -| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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` | +| `-h`, `--help` | Output usage information
`storybook doctor --help` | +| `-c`, `--config-dir` | Directory where to load Storybook configurations from
`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` @@ -307,15 +299,13 @@ Options include: | Option | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-h`, `--help` | Output usage information
`storybook sandbox --help` | -| `-o`, `--output [dir-name]` | Configures the location of the sandbox project
`storybook sandbox --output /my-sandbox-project` | -| `--no-init` | Generates a sandbox project without without initializing Storybook
`storybook sandbox --no-init` | -| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook sandbox --debug` | -| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook sandbox --disable-telemetry` | -| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#crash-reports-disabled-by-default)
`storybook sandbox --enable-crash-reports` | +| `-h`, `--help` | Output usage information
`storybook sandbox --help` | +| `-o`, `--output [dir-name]` | Configures the location of the sandbox project
`storybook sandbox --output /my-sandbox-project` | +| `--no-init` | Generates a sandbox project without without initializing Storybook
`storybook sandbox --no-init` | +| `--debug` | Outputs more logs in the CLI to assist debugging
`storybook sandbox --debug` | +| `--disable-telemetry` | Disables Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#how-to-opt-out)
`storybook sandbox --disable-telemetry` | +| `--enable-crash-reports` | Enables sending crash reports to Storybook's telemetry. Learn more about it [here](../configure/telemetry.md#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). diff --git a/docs/api/csf.mdx b/docs/api/csf.mdx index ef0f6832c342..b2e7ec505bc5 100644 --- a/docs/api/csf.mdx +++ b/docs/api/csf.mdx @@ -7,9 +7,7 @@ title: 'Component Story Format (CSF)' Component Story Format (CSF) is the recommended way to [write stories](../writing-stories/index.md). It's an [open standard](https://github.com/ComponentDriven/csf) based on ES6 modules that is portable beyond Storybook. - -If you have stories written in the older `storiesOf()` syntax, it was removed in Storybook 8.0 and is no longer maintained. We recommend migrating your stories to CSF. See the [migration guide](../migration-guide.md#storiesof-to-csf) for more information. - + If you have stories written in the older `storiesOf()` syntax, it was removed in Storybook 8.0 and is no longer maintained. We recommend migrating your stories to CSF. See the [migration guide](../migration-guide.md#storiesof-to-csf) for more information. In CSF, stories and component metadata are defined as ES Modules. Every component story file consists of a required [default export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#Using_the_default_export) and one or more [named exports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export). @@ -22,15 +20,7 @@ The `component` field is required and used by addons for automatic prop table ge {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -42,23 +32,7 @@ With CSF, every named export in the file represents a story object by default. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -69,7 +43,7 @@ The exported identifiers will be converted to "start case" using Lodash's [start | name | Name | | someName | Some Name | | someNAME | Some NAME | -| some_custom_NAME | Some Custom NAME | +| some\_custom\_NAME | Some Custom NAME | | someName1234 | Some Name 1 2 3 4 | We recommend that all export names to start with a capital letter. @@ -80,17 +54,7 @@ Storybook's `name` configuration element is helpful in specific circumstances. C {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -102,23 +66,7 @@ Consider Storybook’s ["Button" example](../writing-stories/index.md#defining-s {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -126,23 +74,7 @@ Now consider the same example, re-written with args: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -150,23 +82,7 @@ Or even more simply: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -182,57 +98,24 @@ A good use case for the `play` function is a form component. With previous Story {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} When the story renders in the UI, Storybook executes each step defined in the `play` function and runs the assertions without the need for user interaction. + ## Custom render functions -## Custom render functions - -Starting in Storybook 6.4, you can write your stories as JavaScript objects, reducing the boilerplate code you need to generate to test your components, thus improving functionality and usability. `Render` functions are helpful methods to give you additional control over how the story renders. For example, if you were writing a story as an object and you wanted to specify how your component should render, you could write the following: - -{/* prettier-ignore-start */} + Starting in Storybook 6.4, you can write your stories as JavaScript objects, reducing the boilerplate code you need to generate to test your components, thus improving functionality and usability. `Render` functions are helpful methods to give you additional control over how the story renders. For example, if you were writing a story as an object and you wanted to specify how your component should render, you could write the following: - + {/* prettier-ignore-start */} -{/* prettier-ignore-end */} + -When Storybook loads this story, it will detect the existence of a `render` function and adjust the component rendering accordingly based on what's defined. + {/* prettier-ignore-end */} + When Storybook loads this story, it will detect the existence of a `render` function and adjust the component rendering accordingly based on what's defined. ## Storybook export vs. name handling @@ -245,11 +128,7 @@ If you specify the `name` option, it will be used as the story display name in t {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -270,23 +149,7 @@ Consider the following story file: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -294,12 +157,12 @@ When this file renders in Storybook, it treats `ComplexStory` and `SimpleStory` For this particular example, you could achieve the same result in different ways, depending on what's convenient: -- `includeStories: /^[A-Z]/` -- `includeStories: /.*Story$/` -- `includeStories: ['SimpleStory', 'ComplexStory']` -- `excludeStories: /^[a-z]/` -- `excludeStories: /.*Data$/` -- `excludeStories: ['simpleData', 'complexData']` +* `includeStories: /^[A-Z]/` +* `includeStories: /.*Story$/` +* `includeStories: ['SimpleStory', 'ComplexStory']` +* `excludeStories: /^[a-z]/` +* `excludeStories: /.*Data$/` +* `excludeStories: ['simpleData', 'complexData']` The first option is the recommended solution if you follow the best practice of starting story exports with an uppercase letter (i.e., use UpperCamelCase). @@ -309,21 +172,7 @@ In CSF 2, the named exports are always functions that instantiate a component, a {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -333,18 +182,7 @@ Here's the CSF 3 equivalent: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -360,11 +198,7 @@ Here's the CSF 2 implementation: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -374,12 +208,7 @@ In CSF 3, we can spread the `Primary` object to carry over all its annotations: {/* prettier-ignore-start */} - + Learn more about [named story exports](#named-story-exports). @@ -393,21 +222,7 @@ Let's start with a simple CSF 2 story function: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -415,26 +230,10 @@ Now, let's rewrite it as a story object in CSF 3 with an explicit `render` funct {/* prettier-ignore-start */} - + - -Learn more about [render functions](#custom-render-functions). - + Learn more about [render functions](#custom-render-functions). {/* prettier-ignore-end */} @@ -445,18 +244,12 @@ CSF 3 provides default render functions for each renderer. If all you're doing i {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -For more information, see the section on [custom render functions](#custom-render-functions). - + For more information, see the section on [custom render functions](#custom-render-functions). ### Generate titles automatically @@ -465,21 +258,13 @@ Finally, CSF 3 can automatically generate titles. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/doc-block-argtypes.mdx b/docs/api/doc-block-argtypes.mdx index c4d0277bfaeb..54dffe45d7b1 100644 --- a/docs/api/doc-block-argtypes.mdx +++ b/docs/api/doc-block-argtypes.mdx @@ -2,19 +2,18 @@ title: 'ArgTypes' --- - + The `ArgTypes` block can be used to show a static table of [arg types](./argtypes.md) for a given component, as a way to document its interface. - -If you’re looking for a dynamic table that shows a story’s current arg values for a story and supports users changing them, see the [`Controls`](./doc-block-controls.md) block instead. - + If you’re looking for a dynamic table that shows a story’s current arg values for a story and supports users changing them, see the [`Controls`](./doc-block-controls.md) block instead. ![Screenshot of ArgTypes block](./doc-block-argtypes.png) {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -25,6 +24,7 @@ import * as ButtonStories from './Button.stories'; ``` + {/* prettier-ignore-end */} ## ArgTypes @@ -34,37 +34,29 @@ import { ArgTypes } from '@storybook/blocks'; ```
-Configuring with props and parameters + Configuring with props and parameters -ℹ️ Like most blocks, the `ArgTypes` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../writing-stories/parameters.md) in the block's namespace, `parameters.docs.argTypes`. + ℹ️ Like most blocks, the `ArgTypes` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../writing-stories/parameters.md) in the block's namespace, `parameters.docs.argTypes`. -The following `exclude` configurations are equivalent: + The following `exclude` configurations are equivalent: -{/* prettier-ignore-start */} + {/* prettier-ignore-start */} - + -{/* prettier-ignore-end */} + {/* prettier-ignore-end */} -{/* prettier-ignore-start */} -```md -{/* ButtonDocs.mdx */} + {/* prettier-ignore-start */} - -``` -{/* prettier-ignore-end */} + ```md + {/* ButtonDocs.mdx */} + + + ``` -The example above applied the parameter at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level, but it could also be applied at the [project](../writing-stories/parameters.md#global-parameters) or [story](../writing-stories/parameters.md#story-parameters) level. + {/* prettier-ignore-end */} + The example above applied the parameter at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level, but it could also be applied at the [project](../writing-stories/parameters.md#global-parameters) or [story](../writing-stories/parameters.md#story-parameters) level.
### `exclude` @@ -97,6 +89,6 @@ Default: `parameters.docs.argTypes.sort` or `'none'` Specifies how the arg types are sorted. -- **none**: Unsorted, displayed in the same order the arg types are processed in -- **alpha**: Sorted alphabetically, by the arg type's name -- **requiredFirst**: Same as `alpha`, with any required arg types displayed first +* **none**: Unsorted, displayed in the same order the arg types are processed in +* **alpha**: Sorted alphabetically, by the arg type's name +* **requiredFirst**: Same as `alpha`, with any required arg types displayed first diff --git a/docs/api/doc-block-canvas.mdx b/docs/api/doc-block-canvas.mdx index 72f90faaff03..56c768b62fb8 100644 --- a/docs/api/doc-block-canvas.mdx +++ b/docs/api/doc-block-canvas.mdx @@ -2,7 +2,7 @@ title: 'Canvas' --- - + The `Canvas` block is a wrapper around a [`Story`](./doc-block-story.md), featuring a toolbar that allows you to interact with its content while automatically providing the required [`Source`](./doc-block-source.md) snippets. @@ -11,6 +11,7 @@ The `Canvas` block is a wrapper around a [`Story`](./doc-block-story.md), featu When using the Canvas block in MDX, it references a story with the `of` prop: {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -21,12 +22,11 @@ import * as ButtonStories from './Button.stories'; ``` + {/* prettier-ignore-end */} - -In previous versions of Storybook it was possible to pass in arbitrary components as children to `Canvas`. That is deprecated and the `Canvas` block now only supports a single story. - + In previous versions of Storybook it was possible to pass in arbitrary components as children to `Canvas`. That is deprecated and the `Canvas` block now only supports a single story. ## Canvas @@ -36,36 +36,29 @@ import { Canvas } from '@storybook/blocks'; ```
-Configuring with props and parameters + Configuring with props and parameters -ℹ️ Like most blocks, the `Canvas` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../writing-stories/parameters.md) in the block's namespace, `parameters.docs.canvas`. + ℹ️ Like most blocks, the `Canvas` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../writing-stories/parameters.md) in the block's namespace, `parameters.docs.canvas`. -The following `sourceState` configurations are equivalent: + The following `sourceState` configurations are equivalent: -{/* prettier-ignore-start */} + {/* prettier-ignore-start */} - + -{/* prettier-ignore-end */} + {/* prettier-ignore-end */} -{/* prettier-ignore-start */} -```md -{/* ButtonDocs.mdx */} + {/* prettier-ignore-start */} - -``` -{/* prettier-ignore-end */} + ```md + {/* ButtonDocs.mdx */} + + + ``` -The example above applied the parameter at the [story](../writing-stories/parameters.md#story-parameters) level, but it could also be applied at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level or [project](../writing-stories/parameters.md#global-parameters) level. + {/* prettier-ignore-end */} + The example above applied the parameter at the [story](../writing-stories/parameters.md#story-parameters) level, but it could also be applied at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level or [project](../writing-stories/parameters.md#global-parameters) level.
### `additionalActions` @@ -73,6 +66,7 @@ The example above applied the parameter at the [story](../writing-stories/parame Type: {/* prettier-ignore-start */} + ```ts Array<{ title: string | JSX.Element; @@ -81,6 +75,7 @@ Array<{ disabled?: boolean; }>; ``` + {/* prettier-ignore-end */} Default: `parameters.docs.canvas.additionalActions` @@ -88,6 +83,7 @@ Default: `parameters.docs.canvas.additionalActions` Provides any additional custom actions to show in the bottom right corner. These are simple buttons that do anything you specify in the `onClick` function. {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -112,6 +108,7 @@ import * as ButtonStories from './Button.stories'; of={ButtonStories.Primary} /> ``` + {/* prettier-ignore-end */} ### `className` @@ -130,9 +127,9 @@ Default: `parameters.layout` or `parameters.docs.canvas.layout` or `'padded'` Specifies how the canvas should layout the story. -- **centered**: Center the story within the canvas -- **padded**: (default) Add padding to the story -- **fullscreen**: Show the story as-is, without padding +* **centered**: Center the story within the canvas +* **padded**: (default) Add padding to the story +* **fullscreen**: Show the story as-is, without padding In addition to the `parameters.docs.canvas.layout` property or the `layout` prop, the `Canvas` block will respect the `parameters.layout` value that defines [how a story is laid out](../configure/story-layout.md) in the regular story view. @@ -145,6 +142,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 {/* ButtonDocs.mdx */} @@ -158,6 +156,7 @@ import * as HeaderStories from './Header.stories'; it can render Header stories too */} ``` + {/* prettier-ignore-end */} ### `of` @@ -173,9 +172,7 @@ Type: `SourceProps['code'] | SourceProps['format'] | SourceProps['language'] | S Specifies the props passed to the inner `Source` block. For more information, see the `Source` Doc Block [documentation](./doc-block-source.md). - -The dark prop is ignored, as the `Source` block is always rendered in dark mode when shown as part of a `Canvas` block. - + The dark prop is ignored, as the `Source` block is always rendered in dark mode when shown as part of a `Canvas` block. ### `sourceState` @@ -186,9 +183,9 @@ Default: `parameters.docs.canvas.sourceState` or `'hidden'` Specifies the initial state of the source panel. -- **hidden**: the source panel is hidden by default -- **shown**: the source panel is shown by default -- **none**: the source panel is not available and the button to show it is not rendered +* **hidden**: the source panel is hidden by default +* **shown**: the source panel is shown by default +* **none**: the source panel is not available and the button to show it is not rendered ### `story` diff --git a/docs/api/doc-block-colorpalette.mdx b/docs/api/doc-block-colorpalette.mdx index 4d2139126f55..887b69f32822 100644 --- a/docs/api/doc-block-colorpalette.mdx +++ b/docs/api/doc-block-colorpalette.mdx @@ -2,13 +2,14 @@ title: 'ColorPalette' --- - + The `ColorPalette` block allows you to document all color-related items (e.g., swatches) used throughout your project. ![Screenshot of ColorPalette and ColorItem blocks](./doc-block-colorpalette.png) {/* prettier-ignore-start */} + ```md {/* Colors.mdx */} @@ -44,6 +45,7 @@ import { Meta, ColorPalette, ColorItem } from '@storybook/blocks'; /> ``` + {/* prettier-ignore-end */} ## ColorPalette diff --git a/docs/api/doc-block-controls.mdx b/docs/api/doc-block-controls.mdx index 09a677f2ab0b..04a1f1735d25 100644 --- a/docs/api/doc-block-controls.mdx +++ b/docs/api/doc-block-controls.mdx @@ -2,19 +2,18 @@ title: 'Controls' --- - + The `Controls` block can be used to show a dynamic table of args for a given story, as a way to document its interface, and to allow you to change the args for a (separately) rendered story (via the [`Story`](./doc-block-story.md) or [`Canvas`](./doc-block-canvas.md) blocks). - -If you’re looking for a static table that shows a component's arg types with no controls, see the [`ArgTypes`](./doc-block-argtypes.md) block instead. - + If you’re looking for a static table that shows a component's arg types with no controls, see the [`ArgTypes`](./doc-block-argtypes.md) block instead. ![Screenshot of Controls block](./doc-block-controls.png) {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -27,12 +26,11 @@ import * as ButtonStories from './Button.stories' ``` + {/* prettier-ignore-end */} - -The Controls doc block will only have functioning UI controls if you have also installed and registered [`@storybook/addon-controls`](../essentials/controls.md) (included in [`@storybook/addon-essentials`](../essentials/index.md)) and haven't turned off inline stories with the [`inline`](./doc-block-story.md#inline) configuration option. - + The Controls doc block will only have functioning UI controls if you have also installed and registered [`@storybook/addon-controls`](../essentials/controls.md) (included in [`@storybook/addon-essentials`](../essentials/index.md)) and haven't turned off inline stories with the [`inline`](./doc-block-story.md#inline) configuration option. ## Controls @@ -42,42 +40,33 @@ import { Controls } from '@storybook/blocks'; ```
-Configuring with props and parameters + Configuring with props and parameters -ℹ️ Like most blocks, the `Controls` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../writing-stories/parameters.md) in the block's namespace, `parameters.docs.controls`. + ℹ️ Like most blocks, the `Controls` block is configured with props in MDX. Many of those props derive their default value from a corresponding [parameter](../writing-stories/parameters.md) in the block's namespace, `parameters.docs.controls`. -The following `exclude` configurations are equivalent: + The following `exclude` configurations are equivalent: -{/* prettier-ignore-start */} + {/* prettier-ignore-start */} - + -{/* prettier-ignore-end */} + {/* prettier-ignore-end */} -{/* prettier-ignore-start */} -```md -{/* ButtonDocs.mdx */} + {/* prettier-ignore-start */} - -``` -{/* prettier-ignore-end */} + ```md + {/* ButtonDocs.mdx */} + + + ``` -The example above applied the parameter at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level, but it could also be applied at the [project](../writing-stories/parameters.md#global-parameters) or [story](../writing-stories/parameters.md#story-parameters) level. + {/* prettier-ignore-end */} + The example above applied the parameter at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level, but it could also be applied at the [project](../writing-stories/parameters.md#global-parameters) or [story](../writing-stories/parameters.md#story-parameters) level.
- -This API configures Controls blocks used within docs pages. To configure the Controls addon panel, see the [Controls addon docs](../essentials/controls.md). To configure individual controls, you can specify [argTypes](./arg-types.md#control) for each. - + This API configures Controls blocks used within docs pages. To configure the Controls addon panel, see the [Controls addon docs](../essentials/controls.md). To configure individual controls, you can specify [argTypes](./arg-types.md#control) for each. ### `exclude` @@ -110,6 +99,6 @@ Default: `parameters.docs.controls.sort` or `'none'` Specifies how the controls are sorted. -- **none**: Unsorted, displayed in the same order the controls are processed in -- **alpha**: Sorted alphabetically, by the arg type's name -- **requiredFirst**: Same as `alpha`, with any required controls displayed first +* **none**: Unsorted, displayed in the same order the controls are processed in +* **alpha**: Sorted alphabetically, by the arg type's name +* **requiredFirst**: Same as `alpha`, with any required controls displayed first diff --git a/docs/api/doc-block-description.mdx b/docs/api/doc-block-description.mdx index 64e5d96c7f20..b856b142ef55 100644 --- a/docs/api/doc-block-description.mdx +++ b/docs/api/doc-block-description.mdx @@ -2,13 +2,14 @@ title: 'Description' --- - + The `Description` block displays the description for a component, story, or meta, obtained from their respective JSDoc comments. ![Screenshot of Description block](./doc-block-title-subtitle-description.png) {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -19,6 +20,7 @@ import * as ButtonStories from './Button.stories'; ``` + {/* prettier-ignore-end */} ## Description @@ -70,19 +72,12 @@ export const Button = () => ; {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -99,4 +94,5 @@ import * as ButtonStories from './Button.stories'; {/* Shows the description for the Primary export */} ``` + {/* prettier-ignore-end */} diff --git a/docs/api/doc-block-icongallery.mdx b/docs/api/doc-block-icongallery.mdx index 2b2657bfd0cb..35594a48bca4 100644 --- a/docs/api/doc-block-icongallery.mdx +++ b/docs/api/doc-block-icongallery.mdx @@ -2,13 +2,14 @@ title: 'IconGallery' --- - + The `IconGallery` block enables you to easily document React icon components associated with your project, displayed in a neat grid. ![Screenshot of IconGallery and IconItem blocks](./doc-block-icongallery.png) {/* prettier-ignore-start */} + ```md {/* Iconography.mdx */} @@ -53,6 +54,7 @@ import { Icon as IconExample } from './Icon'; ``` + {/* prettier-ignore-end */} ## IconGallery diff --git a/docs/api/doc-block-markdown.mdx b/docs/api/doc-block-markdown.mdx index e6fe188538b9..f794d142b1b8 100644 --- a/docs/api/doc-block-markdown.mdx +++ b/docs/api/doc-block-markdown.mdx @@ -9,6 +9,7 @@ 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 {/* README.md */} @@ -20,9 +21,11 @@ Primary UI component for user interaction import { Button } from "@storybook/design-system"; ``` ```` + {/* prettier-ignore-end */} {/* prettier-ignore-start */} + ```md {/* Header.mdx */} @@ -37,6 +40,7 @@ import { Markdown } from '@storybook/blocks'; {ReadMe} ``` + {/* prettier-ignore-end */} ## Markdown @@ -62,6 +66,7 @@ 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 {/* THIS WON'T WORK, THIS IS TO DEMONSTRATE AN ERROR */} @@ -71,11 +76,13 @@ import ReadMe from './README.md'; {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 @@ -83,11 +90,13 @@ 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 @@ -103,4 +112,5 @@ 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-block-meta.mdx b/docs/api/doc-block-meta.mdx index b3c1322cb3a6..d2de6c7dfb3c 100644 --- a/docs/api/doc-block-meta.mdx +++ b/docs/api/doc-block-meta.mdx @@ -4,10 +4,11 @@ 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 {/* ButtonDocs.mdx */} @@ -16,12 +17,11 @@ 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,6 +45,7 @@ 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 {/* Component.mdx */} @@ -54,6 +55,7 @@ import * as ComponentStories from './component.stories'; {/* This MDX file is now called "Special Docs" */} ``` + {/* prettier-ignore-end */} ### `of` @@ -63,6 +65,7 @@ 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 {/* ButtonDocs.mdx */} @@ -71,6 +74,7 @@ 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: @@ -79,9 +83,7 @@ Attaching an MDX file to a component’s stories with the `of` prop serves two p 2. Attaches the component and its stories to the MDX file, allowing you to use other doc blocks in “attached” mode (for instance to use the `Stories` block). - -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/sidebar-and-urls.md#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/sidebar-and-urls.md#csf-30-auto-titles) decide where it goes. ### `title` @@ -91,6 +93,7 @@ Type: `string` Sets the title of an [unattached](#attached-vs-unattached) MDX file. {/* prettier-ignore-start */} + ```md {/* Introduction.mdx */} @@ -99,12 +102,11 @@ import { Meta } from '@storybook/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.md#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.md#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-block-primary.mdx b/docs/api/doc-block-primary.mdx index 3c5f6a54cdc3..4b1a357aeece 100644 --- a/docs/api/doc-block-primary.mdx +++ b/docs/api/doc-block-primary.mdx @@ -2,13 +2,14 @@ title: 'Primary' --- - + The `Primary` block displays the primary (first defined in the stories file) story, in a [`Story`](./doc-block-story.md) block. It is typically rendered immediately under the title in a docs entry. ![Screenshot of Primary block](./doc-block-primary.png) {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -19,6 +20,7 @@ import * as ButtonStories from './Button.stories'; ``` + {/* prettier-ignore-end */} ## Primary diff --git a/docs/api/doc-block-source.mdx b/docs/api/doc-block-source.mdx index a133a362d3b3..be0a1b74d60b 100644 --- a/docs/api/doc-block-source.mdx +++ b/docs/api/doc-block-source.mdx @@ -2,13 +2,14 @@ title: 'Source' --- - + The `Source` block is used to render a snippet of source code directly. ![Screenshot of Source block](./doc-block-source.png) {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -19,6 +20,7 @@ import * as ButtonStories from './Button.stories'; ``` + {/* prettier-ignore-end */} ## Source @@ -28,36 +30,29 @@ import { Source } from '@storybook/blocks'; ```
-Configuring with props and parameters + 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.md) in the block's namespace, `parameters.docs.source`. + ℹ️ 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.md) in the block's namespace, `parameters.docs.source`. -The following `language` configurations are equivalent: + The following `language` configurations are equivalent: -{/* prettier-ignore-start */} + {/* prettier-ignore-start */} - + -{/* prettier-ignore-end */} + {/* prettier-ignore-end */} -{/* prettier-ignore-start */} -```md -{/* ButtonDocs.mdx */} + {/* prettier-ignore-start */} - -``` -{/* prettier-ignore-end */} + ```md + {/* ButtonDocs.mdx */} -The example above applied the parameter at the [story](../writing-stories/parameters.md#story-parameters) level, but it could also be applied at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level or [project](../writing-stories/parameters.md#global-parameters) level. + + ``` + {/* prettier-ignore-end */} + + The example above applied the parameter at the [story](../writing-stories/parameters.md#story-parameters) level, but it could also be applied at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level or [project](../writing-stories/parameters.md#global-parameters) level.
### `code` @@ -69,6 +64,7 @@ Default: `parameters.docs.source.code` Provides the source code to be rendered. {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -82,6 +78,7 @@ if (isSyntaxHighlighted) { console.log('syntax highlighting is working'); }`} /> ``` + {/* prettier-ignore-end */} ### `dark` @@ -93,21 +90,17 @@ Default: `parameters.docs.source.dark` 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.md)—like it is in [autodocs](../writing-docs/autodocs.md)—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.md)—like it is in [autodocs](../writing-docs/autodocs.md)—it will always use dark mode. + ### `excludeDecorators` -### `excludeDecorators` - -Type: `boolean` - -Default: `parameters.docs.source.excludeDecorators` + Type: `boolean` -Determines if [decorators](../writing-stories/decorators.md) are rendered in the source code snippet. + Default: `parameters.docs.source.excludeDecorators` + Determines if [decorators](../writing-stories/decorators.md) are rendered in the source code snippet. ### `format` @@ -123,9 +116,11 @@ Specifies the formatting used on source code. Both `true` and `'dedent'` have th 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'` @@ -155,12 +150,10 @@ 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.md) and the [`Story` block](./doc-block-story.md) 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.md) and the [`Story` block](./doc-block-story.md) for that story is rendered along with the `Source` block. diff --git a/docs/api/doc-block-stories.mdx b/docs/api/doc-block-stories.mdx index 96195d1a0f09..6d492f564945 100644 --- a/docs/api/doc-block-stories.mdx +++ b/docs/api/doc-block-stories.mdx @@ -2,13 +2,14 @@ title: 'Stories' --- - + The `Stories` block renders the full collection of stories in a stories file. ![Screenshot of Stories block](./doc-block-stories.png) {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -19,6 +20,7 @@ import * as ButtonStories from './Button.stories'; ``` + {/* prettier-ignore-end */} ## Stories @@ -38,9 +40,7 @@ Default: `true` 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-block-story.mdx b/docs/api/doc-block-story.mdx index a438fda53048..e4f2894a6d7a 100644 --- a/docs/api/doc-block-story.mdx +++ b/docs/api/doc-block-story.mdx @@ -2,21 +2,20 @@ title: 'Story' --- - + Stories (component tests) are Storybook's fundamental building blocks. In Storybook Docs, you can render any of your stories from your CSF files in the context of an MDX file with all annotations (parameters, args, loaders, decorators, play function) applied using the `Story` block. - -Typically you want to use the [`Canvas` block](./doc-block-canvas.md) 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.md) 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](./doc-block-story.png) {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -27,6 +26,7 @@ import * as ButtonStories from './Button.stories'; ``` + {/* prettier-ignore-end */} ## Story @@ -36,36 +36,29 @@ import { Story } from '@storybook/blocks'; ```
-Configuring with props and parameters + 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.md) in the block's namespace, `parameters.docs.story`. + ℹ️ 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.md) in the block's namespace, `parameters.docs.story`. -The following `autoplay` configurations are equivalent: + The following `autoplay` configurations are equivalent: -{/* prettier-ignore-start */} + {/* prettier-ignore-start */} - + -{/* prettier-ignore-end */} + {/* prettier-ignore-end */} -{/* prettier-ignore-start */} -```md -{/* ButtonDocs.mdx */} + {/* prettier-ignore-start */} - -``` -{/* prettier-ignore-end */} + ```md + {/* ButtonDocs.mdx */} + + + ``` -The example above applied the parameter at the [story](../writing-stories/parameters.md#story-parameters) level, but it could also be applied at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level or [project](../writing-stories/parameters.md#global-parameters) level. + {/* prettier-ignore-end */} + The example above applied the parameter at the [story](../writing-stories/parameters.md#story-parameters) level, but it could also be applied at the [component](../writing-stories/parameters.md#component-parameters) (or meta) level or [project](../writing-stories/parameters.md#global-parameters) level.
### `autoplay` @@ -97,9 +90,7 @@ Default: `parameters.docs.story.inline` or `true` (for [supported frameworks](.. Determines whether the story is rendered `inline` (in the same browser frame as the other docs content) or in an iframe. - -Setting the `inline` option to false will prevent the associated [controls](./doc-block-controls.md) 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.md) 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` @@ -111,6 +102,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 {/* ButtonDocs.mdx */} @@ -124,6 +116,7 @@ import * as HeaderStories from './Header.stories'; it can render Header stories too */} ``` + {/* prettier-ignore-end */} ### `of` @@ -132,4 +125,4 @@ 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.md#attached-vs-unattached), the primary (first) story will be rendered. - + diff --git a/docs/api/doc-block-subtitle.mdx b/docs/api/doc-block-subtitle.mdx index 0be4f817f15f..505b05a22a24 100644 --- a/docs/api/doc-block-subtitle.mdx +++ b/docs/api/doc-block-subtitle.mdx @@ -2,13 +2,14 @@ title: 'Subtitle' --- - + The `Subtitle` block can serve as a secondary heading for your docs entry. ![Screenshot of Subtitle block](./doc-block-title-subtitle-description.png) {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -16,6 +17,7 @@ import { Subtitle } from '@storybook/blocks'; This is the subtitle ``` + {/* prettier-ignore-end */} ## Subtitle diff --git a/docs/api/doc-block-title.mdx b/docs/api/doc-block-title.mdx index 5b28a9f819d8..a28f563c8110 100644 --- a/docs/api/doc-block-title.mdx +++ b/docs/api/doc-block-title.mdx @@ -2,13 +2,14 @@ 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](./doc-block-title-subtitle-description.png) {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -16,6 +17,7 @@ import { Title } from '@storybook/blocks'; This is the title ``` + {/* prettier-ignore-end */} ## Title diff --git a/docs/api/doc-block-typeset.mdx b/docs/api/doc-block-typeset.mdx index 943dc8b57ffc..4f9448aed594 100644 --- a/docs/api/doc-block-typeset.mdx +++ b/docs/api/doc-block-typeset.mdx @@ -2,7 +2,7 @@ title: 'Typeset' --- - + The `Typeset` block helps document the fonts used throughout your project. diff --git a/docs/api/doc-block-unstyled.mdx b/docs/api/doc-block-unstyled.mdx index 9729bb22604b..5fb011ba1cbf 100644 --- a/docs/api/doc-block-unstyled.mdx +++ b/docs/api/doc-block-unstyled.mdx @@ -7,6 +7,7 @@ The `Unstyled` block is a special block that disables Storybook's default stylin 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 import { Meta, Unstyled } from "@storybook/blocks"; import { Header } from "./Header.tsx"; @@ -26,6 +27,7 @@ import { Header } from "./Header.tsx"; ``` + {/* prettier-ignore-end */} Yields: @@ -33,25 +35,23 @@ Yields: ![Screenshot of Unstyled Doc Block](./doc-block-unstyled.png) - -The other blocks like [`Story`](./doc-block-story.md) and [`Canvas`](./doc-block-canvas.md) 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.md) and [`Canvas`](./doc-block-canvas.md) 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`: -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 */} -{/* prettier-ignore-start */} -```md -
- - - -
-``` -{/* prettier-ignore-end */} + ```md +
+ + + +
+ ``` + {/* prettier-ignore-end */} ## Unstyled @@ -66,4 +66,4 @@ import { Unstyled } from '@storybook/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-block-useof.mdx b/docs/api/doc-block-useof.mdx index f0e2e23cdfcb..a91db0957e71 100644 --- a/docs/api/doc-block-useof.mdx +++ b/docs/api/doc-block-useof.mdx @@ -34,6 +34,7 @@ export const StoryName = ({ of }) => { ``` {/* prettier-ignore-start */} + ```md {/* ButtonDocs.mdx */} @@ -52,6 +53,7 @@ import * as ButtonStories from './Button.stories'; {/* renders "Button" */} ``` + {/* prettier-ignore-end */} ## useOf @@ -59,12 +61,14 @@ import * as ButtonStories from './Button.stories'; ### Type {/* prettier-ignore-start */} + ```ts ( moduleExportOrType: ModuleExport | 'story' | 'meta' | 'component', validTypes?: Array<'story' | 'meta' | 'component'> ) => EnhancedResolvedModuleExportType ``` + {/* prettier-ignore-end */} ### Parameters @@ -79,9 +83,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.md#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/index.mdx b/docs/api/index.mdx index 702182e1074f..7c02e18ba786 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -21,30 +21,38 @@ An overview of all available API references for Storybook. Description + main.js|ts + Storybook's primary configuration file, which specifies your Storybook project's behavior, including the location of your stories, the addons you use, feature flags and other project-specific settings. + preview.js|jsx|ts|tsx + This configuration file controls the way stories are rendered. You can also use it to run code that applies to all stories. + manager.js|ts + This configuration file controls the behavior of Storybook's UI, the manager. + CLI + Storybook is a CLI tool. You can start Storybook in development mode or build a static version of your Storybook. @@ -62,25 +70,31 @@ An overview of all available API references for Storybook. Description + CSF + - Component Story Format (CSF) is the API for writing stories. It's an + Component Story Format (CSF) is the API for writing stories. It's an open standard based on ES6 modules that is portable beyond Storybook. + ArgTypes + ArgTypes specify the behavior of args. 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. + Parameters + Parameters are static metadata used to configure your stories addons in Storybook. They are specified at the story, meta (component), project (global) levels. @@ -97,9 +111,11 @@ An overview of all available API references for Storybook. Description + Doc blocks + Storybook offers several doc blocks to help document your components and other aspects of your project. diff --git a/docs/api/main-config-addons.mdx b/docs/api/main-config-addons.mdx index b03198f935d9..5279e0a8b87d 100644 --- a/docs/api/main-config-addons.mdx +++ b/docs/api/main-config-addons.mdx @@ -12,11 +12,6 @@ For each addon's available options, see their respective [documentation](https:/ {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-babel-default.mdx b/docs/api/main-config-babel-default.mdx index 67e013d7f54b..80f7f3945370 100644 --- a/docs/api/main-config-babel-default.mdx +++ b/docs/api/main-config-babel-default.mdx @@ -9,18 +9,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.md) instead. - + To adjust your Storybook's Babel setup directly—not via an addon—use [`babel`](./main-config-babel.md) instead. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-babel.mdx b/docs/api/main-config-babel.mdx index c087302a7ded..dadb457b1d5d 100644 --- a/docs/api/main-config-babel.mdx +++ b/docs/api/main-config-babel.mdx @@ -9,19 +9,12 @@ Type: `(config: Babel.Config, options: Options) => Babel.Config | Promise - -[Addon authors](../addons/writing-presets.md#babel) should use [`babelDefault`](./main-config-babel-default.md) instead, which is applied to the preview config before any user presets have been applied. - + [Addon authors](../addons/writing-presets.md#babel) should use [`babelDefault`](./main-config-babel-default.md) instead, which is applied to the preview config before any user presets have been applied. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -30,9 +23,7 @@ Customize Storybook's [Babel](https://babeljs.io/) setup. 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-build.mdx b/docs/api/main-config-build.mdx index 3732f17e975a..146d11f70705 100644 --- a/docs/api/main-config-build.mdx +++ b/docs/api/main-config-build.mdx @@ -28,9 +28,7 @@ Type: `TestBuildFlags` Configures Storybook's production builds for performance testing purposes by disabling certain features from the build. When running `build-storybook`, this feature is enabled by setting the `--test` [flag](./cli-options.md#build). - -The options documented on this page are automatically enabled when the `--test` flag is provided to the `build-storybook` 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 `build-storybook` 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. ### `test.disableBlocks` @@ -41,12 +39,7 @@ Excludes the `@storybook/blocks` package from the build, which generates automat {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -58,12 +51,7 @@ Sets the list of addons that will disabled in the build output. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -75,12 +63,7 @@ Enabling this option removes user-written documentation entries in MDX format fr {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -92,12 +75,7 @@ Prevents automatic documentation generated with the [autodocs](../writing-docs/a {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -109,12 +87,7 @@ Disables [automatic argType](./arg-types.md#automatic-argtype-inference) and com {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -126,12 +99,7 @@ Overrides the default behavior of generating source maps for the build. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -143,11 +111,6 @@ Disables [tree shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_s {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-core.mdx b/docs/api/main-config-core.mdx index 7c06497bc387..c14737ab2261 100644 --- a/docs/api/main-config-core.mdx +++ b/docs/api/main-config-core.mdx @@ -37,21 +37,14 @@ Type: Configures Storybook's builder, [Vite](../builders/vite.md) or [Webpack](../builders/webpack.md). + With the new [Framework API](./new-frameworks.md), [`framework.options.builder`](./main-config-framework.md#optionsbuilder) is now the preferred way to configure the builder. -With the new [Framework API](./new-frameworks.md), [`framework.options.builder`](./main-config-framework.md#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. - + You should only use `core.builder.options` if you need to configure a builder that is not part of a framework. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -101,17 +94,12 @@ 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` +* `Cross-Origin-Opener-Policy: same-origin` +* `Cross-Origin-Embedder-Policy: require-corp` {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -123,12 +111,7 @@ Disables the generation of `project.json`, a file containing Storybook metadata {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -140,12 +123,7 @@ Disables Storybook's [telemetry collection](../configure/telemetry.md). {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -157,12 +135,7 @@ Disables Storybook's default Webpack configuration. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -174,12 +147,7 @@ Disables the "What's New" notifications in the UI for new Storybook versions and {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -191,12 +159,7 @@ Enable crash reports to be sent to Storybook [telemetry](../configure/telemetry. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-docs.mdx b/docs/api/main-config-docs.mdx index 056c90c65627..0dcf99b7670c 100644 --- a/docs/api/main-config-docs.mdx +++ b/docs/api/main-config-docs.mdx @@ -24,18 +24,13 @@ Default: `'tag'` Enables or disables automatic documentation for stories. -- `true`: Enables it for all stories -- `false`: Disables it for all stories -- `'tag'`: Enables it for stories tagged with `'autodocs'` +* `true`: Enables it for all stories +* `false`: Disables it for all stories +* `'tag'`: Enables it for stories tagged with `'autodocs'` {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -49,12 +44,7 @@ Name used for generated documentation pages. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -66,11 +56,6 @@ Only show documentation pages in the sidebar (usually set with the `--docs` CLI {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-env.mdx b/docs/api/main-config-env.mdx index f562865ba07b..1d3f46f8b2fb 100644 --- a/docs/api/main-config-env.mdx +++ b/docs/api/main-config-env.mdx @@ -10,11 +10,6 @@ Defines custom Storybook [environment variables](../configure/environment-variab {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-features.mdx b/docs/api/main-config-features.mdx index 1a75ffd7b392..c849603028cc 100644 --- a/docs/api/main-config-features.mdx +++ b/docs/api/main-config-features.mdx @@ -23,12 +23,7 @@ Apply decorators from preview.js before decorators from addons or frameworks. [M {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -42,11 +37,6 @@ Filter args with a "target" on the type from the render function. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-framework.mdx b/docs/api/main-config-framework.mdx index 3cd5f3d37f60..07293f93db19 100644 --- a/docs/api/main-config-framework.mdx +++ b/docs/api/main-config-framework.mdx @@ -12,12 +12,7 @@ Configures Storybook based on a set of [framework-specific](../configure/framewo {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-indexers.mdx b/docs/api/main-config-indexers.mdx index a1c7b394ffc8..a02e89d0c840 100644 --- a/docs/api/main-config-indexers.mdx +++ b/docs/api/main-config-indexers.mdx @@ -5,9 +5,7 @@ title: 'indexers' (⚠️ **Experimental**) - -While this feature is experimental, it must be specified by the `experimental_indexers` property of [`StorybookConfig`](./main-config.md). - + While this feature is experimental, it must be specified by the `experimental_indexers` property of [`StorybookConfig`](./main-config.md). Parent: [main.js|ts configuration](./main-config.md) @@ -22,12 +20,7 @@ They are defined as a function that returns the full list of indexers, including {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -148,7 +141,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` @@ -176,12 +169,7 @@ Most of the time, you should **not** specify a title, so that your indexer will {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -199,7 +187,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.md) 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.md) 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.md) and/or [Webpack](../builders/webpack.md)), and we recommend using [unplugin](https://github.com/unjs/unplugin) to create plugins for multiple builders. @@ -271,101 +259,90 @@ export const Primary = { Some example usages of custom indexers include:
+ Generating stories dynamically from fixture data or API endpoints -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. -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 */} + {/* prettier-ignore-start */} - + -{/* prettier-ignore-end */} + {/* 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: + ``` -```ts -// vite-plugin-storybook-json-stories.ts + 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: -import type { PluginOption } from 'vite'; -import fs from 'fs/promises'; + ```ts + // vite-plugin-storybook-json-stories.ts -function JsonStoriesPlugin(): PluginOption { - return { - name: 'vite-plugin-storybook-json-stories', - load(id) { - if (!id.startsWith('virtual:jsonstories')) { - return; - } + import type { PluginOption } from 'vite'; + import fs from 'fs/promises'; - const [, fileName, componentName] = id.split('--'); - const content = JSON.parse(fs.readFileSync(fileName)); + function JsonStoriesPlugin(): PluginOption { + return { + name: 'vite-plugin-storybook-json-stories', + load(id) { + if (!id.startsWith('virtual:jsonstories')) { + return; + } - const { componentPath, stories } = getComponentStoriesFromJson(content, componentName); + const [, fileName, componentName] = id.split('--'); + const content = JSON.parse(fs.readFileSync(fileName)); - return ` - import ${componentName} from '${componentPath}'; + const { componentPath, stories } = getComponentStoriesFromJson(content, componentName); - export default { component: ${componentName} }; + return ` + import ${componentName} from '${componentPath}'; - ${stories.map((story) => `export const ${story.name} = ${story.config};\n`)} - `; - }, - }; -} -``` + export default { component: ${componentName} }; + ${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.
diff --git a/docs/api/main-config-log-level.mdx b/docs/api/main-config-log-level.mdx index 259338eb57c8..0507771bee04 100644 --- a/docs/api/main-config-log-level.mdx +++ b/docs/api/main-config-log-level.mdx @@ -12,11 +12,6 @@ Configures Storybook's logs in the browser terminal. Useful for debugging. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-manager-head.mdx b/docs/api/main-config-manager-head.mdx index bb9135ab2451..62863559a1e4 100644 --- a/docs/api/main-config-manager-head.mdx +++ b/docs/api/main-config-manager-head.mdx @@ -9,20 +9,13 @@ Type: `(head: string) => string` Programmatically adjust the manager's `` of your Storybook. For example, load a custom font or add a script. Most often used by [addon authors](../addons/writing-presets.md#ui-configuration). - -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-preview-annotations.mdx b/docs/api/main-config-preview-annotations.mdx index d5a4f91298d9..82bf4817941b 100644 --- a/docs/api/main-config-preview-annotations.mdx +++ b/docs/api/main-config-preview-annotations.mdx @@ -9,9 +9,7 @@ Type: `string[] | ((config: string[], options: Options) => string[] | Promise - -Mostly used by [frameworks](../contribute/framework.md#previewjs-example). Storybook users and [addon authors](../addons/writing-presets.md) should add scripts to [`preview.js`](../configure/index.md#configure-story-rendering) instead. - + Mostly used by [frameworks](../contribute/framework.md#previewjs-example). Storybook users and [addon authors](../addons/writing-presets.md) should add scripts to [`preview.js`](../configure/index.md#configure-story-rendering) instead. ```ts diff --git a/docs/api/main-config-preview-body.mdx b/docs/api/main-config-preview-body.mdx index 133d8d2433f0..6ba4d69f0e0c 100644 --- a/docs/api/main-config-preview-body.mdx +++ b/docs/api/main-config-preview-body.mdx @@ -9,20 +9,13 @@ Type: `(body: string) => string` Programmatically adjust the [preview ``](../configure/story-rendering.md#adding-to-body) of your Storybook. Most often used by [addon authors](../addons/writing-presets.md#ui-configuration). - -If you don't need to programmatically adjust the preview body, you can add scripts and styles to [`preview-body.html`](../configure/story-rendering.md#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.md#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-preview-head.mdx b/docs/api/main-config-preview-head.mdx index e2afd1e0c933..960e2b0b2625 100644 --- a/docs/api/main-config-preview-head.mdx +++ b/docs/api/main-config-preview-head.mdx @@ -9,20 +9,13 @@ Type: `(head: string) => string` Programmatically adjust the [preview ``](../configure/story-rendering.md#adding-to-head) of your Storybook. Most often used by [addon authors](../addons/writing-presets.md#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.md#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.md#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-refs.mdx b/docs/api/main-config-refs.mdx index 85ab48c0534f..e4ae814ba826 100644 --- a/docs/api/main-config-refs.mdx +++ b/docs/api/main-config-refs.mdx @@ -18,12 +18,7 @@ Configures [Storybook composition](../sharing/storybook-composition.md). {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -33,12 +28,7 @@ You can use a function to dynamically configure refs: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -48,11 +38,6 @@ Some package dependencies automatically [compose their Storybook in yours](../sh {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-static-dirs.mdx b/docs/api/main-config-static-dirs.mdx index 8b02703cfe10..7d32621fdf60 100644 --- a/docs/api/main-config-static-dirs.mdx +++ b/docs/api/main-config-static-dirs.mdx @@ -10,12 +10,7 @@ Sets a list of directories of [static files](../configure/images-and-assets.md#s {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -25,11 +20,6 @@ You can also use a configuration object to define the directories: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-stories.mdx b/docs/api/main-config-stories.mdx index 928ff2d81948..c0a2240a4728 100644 --- a/docs/api/main-config-stories.mdx +++ b/docs/api/main-config-stories.mdx @@ -24,21 +24,14 @@ Configures Storybook to load stories from the specified locations. The intention {/* 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). -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. - + Keep in mind that some addons may assume Storybook's default naming convention. ## With an array of globs @@ -49,12 +42,7 @@ Stories are loaded in the order they are defined in the array. This allows you t {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -66,12 +54,7 @@ For example, if you wanted to load your stories from a `packages/components` dir {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -116,20 +99,13 @@ When [auto-titling](../configure/sidebar-and-urls.md#csf-30-auto-titles), prefix ## 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-swc.mdx b/docs/api/main-config-swc.mdx index 23a09f970ed2..4d67bd8b4c32 100644 --- a/docs/api/main-config-swc.mdx +++ b/docs/api/main-config-swc.mdx @@ -10,12 +10,7 @@ Customize Storybook's [SWC](https://swc.rs/) setup for Webpack-based projects en {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-typescript.mdx b/docs/api/main-config-typescript.mdx index 9e930be7a9ff..cdcd4b2e98e6 100644 --- a/docs/api/main-config-typescript.mdx +++ b/docs/api/main-config-typescript.mdx @@ -6,30 +6,26 @@ Parent: [main.js|ts configuration](./main-config.md) Type: - - -```ts -{ - check?: boolean; - checkOptions?: CheckOptions; - reactDocgen?: 'react-docgen' | 'react-docgen-typescript' | false; - reactDocgenTypescriptOptions?: ReactDocgenTypescriptOptions; - 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; -} -``` - + ```ts + { + check?: boolean; + checkOptions?: CheckOptions; + skipCompiler?: boolean; + } + ``` Configures how Storybook handles [TypeScript files](../configure/typescript.md). @@ -42,11 +38,7 @@ Optionally run [fork-ts-checker-webpack-plugin](https://github.com/TypeStrong/fo {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -58,53 +50,39 @@ Options to pass to `fork-ts-checker-webpack-plugin`, if [enabled](#check). See [ {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - + + ## `reactDocgen` -## `reactDocgen` + Type: `'react-docgen' | 'react-docgen-typescript' | false` -Type: `'react-docgen' | 'react-docgen-typescript' | false` + Default: -Default: + * `false`: if `@storybook/react` is not installed + * `'react-docgen'`: if `@storybook/react` is installed -- `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. -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-start */} -{/* prettier-ignore-start */} + - + {/* prettier-ignore-end */} -{/* 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](https://github.com/hipstersmoothie/react-docgen-typescript-plugin). -Configures the options to pass to `react-docgen-typescript-plugin` if `react-docgen-typescript` is enabled. See [docs for available options](https://github.com/hipstersmoothie/react-docgen-typescript-plugin). + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} - - - -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} ## `skipCompiler` @@ -115,10 +93,6 @@ Disable parsing of TypeScript files through the compiler, which is used for Webp {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-vite-final.mdx b/docs/api/main-config-vite-final.mdx index 3e91e2b09a84..ffb9b04600a5 100644 --- a/docs/api/main-config-vite-final.mdx +++ b/docs/api/main-config-vite-final.mdx @@ -10,12 +10,7 @@ Customize Storybook's Vite setup when using the [Vite builder](../builders/vite. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config-webpack-final.mdx b/docs/api/main-config-webpack-final.mdx index b41ac7023175..7b4cb00af1e3 100644 --- a/docs/api/main-config-webpack-final.mdx +++ b/docs/api/main-config-webpack-final.mdx @@ -10,12 +10,7 @@ Customize Storybook's Webpack setup when using the [webpack builder](../builders {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/main-config.mdx b/docs/api/main-config.mdx index 892098c2a80d..68e3b10db2d6 100644 --- a/docs/api/main-config.mdx +++ b/docs/api/main-config.mdx @@ -12,12 +12,7 @@ A typical Storybook configuration file looks like this: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -25,25 +20,25 @@ A typical Storybook configuration file looks like this: An object to configure Storybook containing the following properties: -- [`framework`](./main-config-framework.md) (Required) -- [`stories`](./main-config-stories.md) (Required) -- [`addons`](./main-config-addons.md) -- [`babel`](./main-config-babel.md) -- [`babelDefault`](./main-config-babel-default.md) -- [`build`](./main-config-build.md) -- [`core`](./main-config-core.md) -- [`docs`](./main-config-docs.md) -- [`env`](./main-config-env.md) -- [`features`](./main-config-features.md) -- [`indexers`](./main-config-indexers.md) (⚠️ Experimental) -- [`logLevel`](./main-config-log-level.md) -- [`managerHead`](./main-config-manager-head.md) -- [`previewAnnotations`](./main-config-preview-annotations.md) -- [`previewBody`](./main-config-preview-body.md) -- [`previewHead`](./main-config-preview-head.md) -- [`refs`](./main-config-refs.md) -- [`staticDirs`](./main-config-static-dirs.md) -- [`swc`](./main-config-swc.md) -- [`typescript`](./main-config-typescript.md) -- [`viteFinal`](./main-config-vite-final.md) -- [`webpackFinal`](./main-config-webpack-final.md) +* [`framework`](./main-config-framework.md) (Required) +* [`stories`](./main-config-stories.md) (Required) +* [`addons`](./main-config-addons.md) +* [`babel`](./main-config-babel.md) +* [`babelDefault`](./main-config-babel-default.md) +* [`build`](./main-config-build.md) +* [`core`](./main-config-core.md) +* [`docs`](./main-config-docs.md) +* [`env`](./main-config-env.md) +* [`features`](./main-config-features.md) +* [`indexers`](./main-config-indexers.md) (⚠️ Experimental) +* [`logLevel`](./main-config-log-level.md) +* [`managerHead`](./main-config-manager-head.md) +* [`previewAnnotations`](./main-config-preview-annotations.md) +* [`previewBody`](./main-config-preview-body.md) +* [`previewHead`](./main-config-preview-head.md) +* [`refs`](./main-config-refs.md) +* [`staticDirs`](./main-config-static-dirs.md) +* [`swc`](./main-config-swc.md) +* [`typescript`](./main-config-typescript.md) +* [`viteFinal`](./main-config-vite-final.md) +* [`webpackFinal`](./main-config-webpack-final.md) diff --git a/docs/api/new-frameworks.mdx b/docs/api/new-frameworks.mdx index cf7baf78893e..cd5f5bca0c40 100644 --- a/docs/api/new-frameworks.mdx +++ b/docs/api/new-frameworks.mdx @@ -45,11 +45,7 @@ For example, here’s the boilerplate to start the dev server with `storybook de {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -63,11 +59,7 @@ Let’s look at the `@storybook/vue`’s options definition: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -79,11 +71,7 @@ While developing your custom framework, not maintained by Storybook, you can spe {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -103,13 +91,7 @@ Consider the following React story: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -121,14 +103,7 @@ Consider the following hypothetical example: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -140,11 +115,7 @@ The framework's render function is the entity responsible for converting the ren {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -154,11 +125,7 @@ On the client side, the key file is [`src/client/preview.js`](../configure/index {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -166,11 +133,7 @@ The globals file typically sets up a single global variable that client-side cod {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/api/parameters.mdx b/docs/api/parameters.mdx index e37f118fdf16..27dc0ed03b8e 100644 --- a/docs/api/parameters.mdx +++ b/docs/api/parameters.mdx @@ -7,48 +7,28 @@ Parameters are static metadata used to configure your [stories](../get-started/w ## Story parameters
- -ℹ️ Parameters specified at the story level will [override](#parameter-inheritance) those specified at the project level and meta (component) level. - + ℹ️ Parameters specified at the story level will [override](#parameter-inheritance) those specified at the project level and meta (component) level.
Parameters specified at the story level apply to that story only. They are defined in the `parameters` property of the story (named export): {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} ## Meta parameters
- -ℹ️ Parameters specified at the meta (component) level will [override](#parameter-inheritance) those specified at the project level. - + ℹ️ Parameters specified at the meta (component) level will [override](#parameter-inheritance) those specified at the project level.
Parameter's specified in a [CSF](../writing-stories/index.md#component-story-format-csf) file's meta configuration apply to all stories in that file. They are defined in the `parameters` property of the `meta` (default export): {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -58,12 +38,7 @@ Parameters specified at the project (global) level apply to **all stories** in y {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -79,9 +54,9 @@ Default: `'padded'` Specifies how the canvas should [lay out the story](../configure/story-layout.md). -- **centered**: Center the story within the canvas -- **padded**: (default) Add padding to the story -- **fullscreen**: Show the story as-is, without padding +* **centered**: Center the story within the canvas +* **padded**: (default) Add padding to the story +* **fullscreen**: Show the story as-is, without padding ### `options` @@ -94,9 +69,7 @@ Type: ``` - -The `options` parameter can _only_ be applied at the [project level](#project-parameters). - + The `options` parameter can *only* be applied at the [project level](#project-parameters). #### `options.storySort` @@ -125,13 +98,13 @@ Specifies the order in which stories are displayed in the Storybook UI. When specifying a configuration object, the following options are available: -- **includeNames**: Whether to include the story name in the sorting algorithm. Defaults to `false`. -- **locales**: The locale to use when sorting stories. Defaults to your system locale. -- **method**: The sorting method to use. Defaults to `alphabetical`. - - **alphabetical**: Sort stories alphabetically by name. - - **alphabetical-by-kind**: Sort stories alphabetically by kind, then by name. - - **custom**: Use a custom sorting function. -- **order**: Stories in the specified order will be displayed first, in the order specified. All other stories will be displayed after, in alphabetical order. The order array can accept a nested array to sort 2nd-level story kinds, e.g. `['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components']`. +* **includeNames**: Whether to include the story name in the sorting algorithm. Defaults to `false`. +* **locales**: The locale to use when sorting stories. Defaults to your system locale. +* **method**: The sorting method to use. Defaults to `alphabetical`. + * **alphabetical**: Sort stories alphabetically by name. + * **alphabetical-by-kind**: Sort stories alphabetically by kind, then by name. + * **custom**: Use a custom sorting function. +* **order**: Stories in the specified order will be displayed first, in the order specified. All other stories will be displayed after, in alphabetical order. The order array can accept a nested array to sort 2nd-level story kinds, e.g. `['Intro', 'Pages', ['Home', 'Login', 'Admin'], 'Components']`. When specifying a custom sorting function, the function behaves like a typical JavaScript sorting function. It accepts two stories to compare and returns a number. For example: @@ -186,19 +159,19 @@ Default: `false` Unhandled errors might cause false positive assertions. Setting this to `true` will prevent the [play function](../writing-stories/play-function.md) from failing and showing a warning when unhandled errors are thrown during execution. ---- +*** ### Essential addons All other parameters are contributed by addons. The [essential addon's](../essentials/index.md) parameters are documented on their individual pages: -- [Actions](../essentials/actions.md#parameters) -- [Backgrounds](../essentials/backgrounds.md#parameters) -- [Controls](../essentials/controls.md#parameters) -- [Highlight](../essentials/highlight.md#parameters) -- [Interactions](../essentials/interactions.md#parameters) -- [Measure & Outline](../essentials/measure-and-outline.md#parameters) -- [Viewport](../essentials/viewport.md#parameters) +* [Actions](../essentials/actions.md#parameters) +* [Backgrounds](../essentials/backgrounds.md#parameters) +* [Controls](../essentials/controls.md#parameters) +* [Highlight](../essentials/highlight.md#parameters) +* [Interactions](../essentials/interactions.md#parameters) +* [Measure & Outline](../essentials/measure-and-outline.md#parameters) +* [Viewport](../essentials/viewport.md#parameters) ## Parameter inheritance @@ -211,9 +184,7 @@ When specifying parameters, they are merged together in order of increasing spec 3. Story parameters
- -ℹ️ Parameters are **merged**, so objects are deep-merged, but arrays and other properties are overwritten. - + ℹ️ Parameters are **merged**, so objects are deep-merged, but arrays and other properties are overwritten.
In other words, the following specifications of parameters: diff --git a/docs/api/portable-stories-jest.mdx b/docs/api/portable-stories-jest.mdx index c72a3b1639c8..ea4080b980f2 100644 --- a/docs/api/portable-stories-jest.mdx +++ b/docs/api/portable-stories-jest.mdx @@ -7,316 +7,275 @@ title: 'Portable stories in Jest' export const SUPPORTED_RENDERERS = ['react', 'vue']; + + Portable stories in Jest are currently only supported in [React](?renderer=react) and [Vue](?renderer=vue) projects. + - - -Portable stories in Jest are currently only supported in [React](?renderer=react) and [Vue](?renderer=vue) projects. - - - -{/* End non-supported renderers */} - + {/* End non-supported renderers */} + Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments, such as [Jest](https://jestjs.io). -Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments, such as [Jest](https://jestjs.io). - -Normally, Storybook composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Jest tests, you must handle the story pipeline yourself, which is what the [`composeStories`](#composestories) and [`composeStory`](#composestory) functions enable. - - - - - -**Using `Next.js`?** You need to do three things differently when using portable stories in Jest with Next.js projects: - -- Configure the [`next/jest.js` transformer](https://nextjs.org/docs/pages/building-your-application/testing/jest#manual-setup), which will handle all of the necessary Next.js configuration for you. -- Import [`composeStories`](#composestories) or [`composeStory`](#composestory) from the `@storybook/nextjs` package (e.g. `import { composeStories } from '@storybook/nextjs'`). -- Set up [internal module aliases](../get-started/nextjs.md#storybooknextjsexport-mocks) to ensure the framework configuration works correctly and to be able to mock and assert on them. + Normally, Storybook composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Jest tests, you must handle the story pipeline yourself, which is what the [`composeStories`](#composestories) and [`composeStory`](#composestory) functions enable. - + + + **Using `Next.js`?** You need to do three things differently when using portable stories in Jest with Next.js projects: - - -## composeStories - -`composeStories` will process the component's stories you specify, compose each of them with the necessary [annotations](#annotations), and return an object containing the composed stories. - -By default, the composed story will render the component with the [args](../writing-stories/args.md) that are defined in the story. You can also pass any props to the component in your test and those props will override the values passed in the story's args. - -{/* prettier-ignore-start */} + * Configure the [`next/jest.js` transformer](https://nextjs.org/docs/pages/building-your-application/testing/jest#manual-setup), which will handle all of the necessary Next.js configuration for you. + * Import [`composeStories`](#composestories) or [`composeStory`](#composestory) from the `@storybook/nextjs` package (e.g. `import { composeStories } from '@storybook/nextjs'`). + * Set up [internal module aliases](../get-started/nextjs.md#storybooknextjsexport-mocks) to ensure the framework configuration works correctly and to be able to mock and assert on them. + + - + ## composeStories -{/* prettier-ignore-end */} + `composeStories` will process the component's stories you specify, compose each of them with the necessary [annotations](#annotations), and return an object containing the composed stories. -### Type + By default, the composed story will render the component with the [args](../writing-stories/args.md) that are defined in the story. You can also pass any props to the component in your test and those props will override the values passed in the story's args. -{/* prettier-ignore-start */} -```ts -( - csfExports: CSF file exports, - projectAnnotations?: ProjectAnnotations -) => Record -``` -{/* prettier-ignore-end */} + {/* prettier-ignore-start */} -### Parameters + -#### `csfExports` + {/* prettier-ignore-end */} -(**Required**) + ### Type -Type: CSF file exports + {/* prettier-ignore-start */} -Specifies which component's stories you want to compose. Pass the **full set of exports** from the CSF file (not the default export!). E.g. `import * as stories from './Button.stories'` + ```ts + ( + csfExports: CSF file exports, + projectAnnotations?: ProjectAnnotations + ) => Record + ``` -#### `projectAnnotations` + {/* prettier-ignore-end */} -Type: `ProjectAnnotation | ProjectAnnotation[]` + ### Parameters -Specifies the project annotations to be applied to the composed stories. + #### `csfExports` -This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter. + (**Required**) -This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`. + Type: CSF file exports -### Return + Specifies which component's stories you want to compose. Pass the **full set of exports** from the CSF file (not the default export!). E.g. `import * as stories from './Button.stories'` -Type: `Record` + #### `projectAnnotations` -An object where the keys are the names of the stories and the values are the composed stories. + Type: `ProjectAnnotation | ProjectAnnotation[]` -Additionally, the composed story will have the following properties: + Specifies the project annotations to be applied to the composed stories. -| Property | Type | Description | -| ---------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| storyName | `string` | The story's name | -| args | `Record` | The story's [args](../writing-stories/args.md) | -| argTypes | `ArgType` | The story's [argTypes](./arg-types.md) | -| id | `string` | The story's id | -| parameters | `Record` | The story's [parameters](./parameters.md) | -| load | `() => Promise` | [Prepares](#3-prepare) the story for rendering and and cleans up all previous stories | -| play | `(context?: StoryContext) => Promise \| undefined` | Executes the [play function](#5-play) of a given story | + This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter. -## composeStory + This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`. -You can use `composeStory` if you wish to compose a single story for a component. + ### Return -{/* prettier-ignore-start */} + Type: `Record` - + An object where the keys are the names of the stories and the values are the composed stories. -{/* prettier-ignore-end */} + Additionally, the composed story will have the following properties: -### Type + | Property | Type | Description | + | ---------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------- | + | storyName | `string` | The story's name | + | args | `Record` | The story's [args](../writing-stories/args.md) | + | argTypes | `ArgType` | The story's [argTypes](./arg-types.md) | + | id | `string` | The story's id | + | parameters | `Record` | The story's [parameters](./parameters.md) | + | load | `() => Promise` | [Prepares](#3-prepare) the story for rendering and and cleans up all previous stories | + | play | `(context?: StoryContext) => Promise \| undefined` | Executes the [play function](#5-play) of a given story | -{/* prettier-ignore-start */} -```ts -( - story: Story export, - componentAnnotations: Meta, - projectAnnotations?: ProjectAnnotations, - exportsName?: string -) => ComposedStoryFn -``` -{/* prettier-ignore-end */} + ## composeStory -### Parameters + You can use `composeStory` if you wish to compose a single story for a component. -#### `story` + {/* prettier-ignore-start */} -(**Required**) + -Type: `Story export` + {/* prettier-ignore-end */} -Specifies which story you want to compose. + ### Type -#### `componentAnnotations` + {/* prettier-ignore-start */} -(**Required**) + ```ts + ( + story: Story export, + componentAnnotations: Meta, + projectAnnotations?: ProjectAnnotations, + exportsName?: string + ) => ComposedStoryFn + ``` -Type: `Meta` + {/* prettier-ignore-end */} -The default export from the stories file containing the [`story`](#story). + ### Parameters -#### `projectAnnotations` + #### `story` -Type: `ProjectAnnotation | ProjectAnnotation[]` + (**Required**) -Specifies the project annotations to be applied to the composed story. + Type: `Story export` -This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter. + Specifies which story you want to compose. -This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`. + #### `componentAnnotations` -#### `exportsName` + (**Required**) -Type: `string` + Type: `Meta` -You probably don't need this. Because `composeStory` accepts a single story, it does not have access to the name of that story's export in the file (like `composeStories` does). If you must ensure unique story names in your tests and you cannot use `composeStories`, you can pass the name of the story's export here. + The default export from the stories file containing the [`story`](#story). -### Return + #### `projectAnnotations` -Type: `ComposedStoryFn` + Type: `ProjectAnnotation | ProjectAnnotation[]` -A single [composed story](#return). + Specifies the project annotations to be applied to the composed story. -## setProjectAnnotations + This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter. -This API should be called once, before the tests run, typically in a [setup file](https://jestjs.io/docs/configuration#setupfiles-array). This will make sure that whenever `composeStories` or `composeStory` are called, the project annotations are taken into account as well. + This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`. - + #### `exportsName` - + Type: `string` -**Using `Next.js`?** When you import [`composeStories`](#composestories) or [`composeStory`](#composestory) from the `@storybook/nextjs` package (e.g. `import { composeStories } from '@storybook/nextjs'`), you probably do not need to call `setProjectAnnotations` yourself. The Next.js framework will handle this for you. + You probably don't need this. Because `composeStory` accepts a single story, it does not have access to the name of that story's export in the file (like `composeStories` does). If you must ensure unique story names in your tests and you cannot use `composeStories`, you can pass the name of the story's export here. -If you are using an addon that is required for your stories to render, you will still need to include that addon's `preview` export in the project annotations set. See the example and callout below. - - - -

- - + ### Return -```ts -// setup-portable-stories.ts -// Replace with your renderer, e.g. nextjs, react, vue3 -import { setProjectAnnotations } from '@storybook/'; -import * as addonAnnotations from 'my-addon/preview'; -import * as previewAnnotations from './.storybook/preview'; + Type: `ComposedStoryFn` -setProjectAnnotations([previewAnnotations, addonAnnotations]); -``` + A single [composed story](#return). - + ## setProjectAnnotations -Sometimes a story can require an addon's [decorator](../writing-stories/decorators.md) or [loader](../writing-stories/loaders.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set. See `addonAnnotations` in the example above. + This API should be called once, before the tests run, typically in a [setup file](https://jestjs.io/docs/configuration#setupfiles-array). This will make sure that whenever `composeStories` or `composeStory` are called, the project annotations are taken into account as well. -Note: If the addon doesn't automatically apply the decorator or loader itself, but instead exports them for you to apply manually in `.storybook/preview.js|ts` (e.g. using `withThemeFromJSXProvider` from [@storybook/addon-themes](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider)), then you do not need to do anything else. They are already included in the `previewAnnotations` in the example above. + + + **Using `Next.js`?** When you import [`composeStories`](#composestories) or [`composeStory`](#composestory) from the `@storybook/nextjs` package (e.g. `import { composeStories } from '@storybook/nextjs'`), you probably do not need to call `setProjectAnnotations` yourself. The Next.js framework will handle this for you. - + If you are using an addon that is required for your stories to render, you will still need to include that addon's `preview` export in the project annotations set. See the example and callout below. + -### Type +

+ -```ts -(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void -``` + ```ts + // setup-portable-stories.ts + // Replace with your renderer, e.g. nextjs, react, vue3 + import { setProjectAnnotations } from '@storybook/'; + import * as addonAnnotations from 'my-addon/preview'; + import * as previewAnnotations from './.storybook/preview'; -### Parameters + setProjectAnnotations([previewAnnotations, addonAnnotations]); + ``` -#### `projectAnnotations` + + Sometimes a story can require an addon's [decorator](../writing-stories/decorators.md) or [loader](../writing-stories/loaders.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set. See `addonAnnotations` in the example above. -(**Required**) + Note: If the addon doesn't automatically apply the decorator or loader itself, but instead exports them for you to apply manually in `.storybook/preview.js|ts` (e.g. using `withThemeFromJSXProvider` from [@storybook/addon-themes](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider)), then you do not need to do anything else. They are already included in the `previewAnnotations` in the example above. + -Type: `ProjectAnnotation | ProjectAnnotation[]` + ### Type -A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories. + ```ts + (projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void + ``` -## Annotations + ### Parameters -Annotations are the metadata applied to a story, like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project. + #### `projectAnnotations` -## Story pipeline + (**Required**) -To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline: + Type: `ProjectAnnotation | ProjectAnnotation[]` -![A flow diagram of the story pipeline. First, set project annotations. Storybook automatically collects decorators etc. which are exported by addons and the .storybook/preview file. .storybook/preview.js produces project annotations; some-addon/preview produces addon annotations. Second, prepare. Storybook gathers all the metadata required for a story to be composed. Select.stories.js produces component annotations from the default export and story annotations from the named export. Third, load. Storybook executes all loaders (async). Fourth, render. Storybook renders the story as a component. Illustration of the rendered Select component. Fifth, play. Storybook runs the play function (interacting with component). Illustration of the renderer Select component, now open.](story-pipeline.png) + A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories. -When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment: + ## Annotations -### 1. Apply project-level annotations + Annotations are the metadata applied to a story, like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project. -[Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotatations are those defined in your `.storybook/preview.js` file and by addons you're using. In portable stories, these annotations are not applied automatically—you must apply them yourself. + ## Story pipeline -👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API. + To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline: -### 2. Compose + ![A flow diagram of the story pipeline. First, set project annotations. Storybook automatically collects decorators etc. which are exported by addons and the .storybook/preview file. .storybook/preview.js produces project annotations; some-addon/preview produces addon annotations. Second, prepare. Storybook gathers all the metadata required for a story to be composed. Select.stories.js produces component annotations from the default export and story annotations from the named export. Third, load. Storybook executes all loaders (async). Fourth, render. Storybook renders the story as a component. Illustration of the rendered Select component. Fifth, play. Storybook runs the play function (interacting with component). Illustration of the renderer Select component, now open.](story-pipeline.png) -The story is prepared by running [`composeStories`](#composestories) or [`composeStory`](#composestory). You do not need to do anything for this step. + When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment: -### 3. Prepare + ### 1. Apply project-level annotations -Stories can prepare data they need (e.g. setting up some mocks or fetching data) before rendering by defining [loaders](../writing-stories/loaders.md) or [beforeEach](../writing-tests/interaction-testing.md#run-code-before-each-test). In portable stories, loaders and beforeEach are not applied automatically — you have to apply them yourself. + [Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotatations are those defined in your `.storybook/preview.js` file and by addons you're using. In portable stories, these annotations are not applied automatically—you must apply them yourself. -👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed story will return a `load` method to be called **before** it is rendered. + 👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API. - + ### 2. Compose -It is recommended to always run `load` before rendering, even if the story doesn't have any loaders or beforeEach applied. By doing so, you ensure that the tests are cleaned up properly to maintain isolation and you will not have to update your test if you later add them to your story. + The story is prepared by running [`composeStories`](#composestories) or [`composeStory`](#composestory). You do not need to do anything for this step. - + ### 3. Prepare -{/* prettier-ignore-start */} + Stories can prepare data they need (e.g. setting up some mocks or fetching data) before rendering by defining [loaders](../writing-stories/loaders.md) or [beforeEach](../writing-tests/interaction-testing.md#run-code-before-each-test). In portable stories, loaders and beforeEach are not applied automatically — you have to apply them yourself. - + 👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed story will return a `load` method to be called **before** it is rendered. -{/* prettier-ignore-end */} + + It is recommended to always run `load` before rendering, even if the story doesn't have any loaders or beforeEach applied. By doing so, you ensure that the tests are cleaned up properly to maintain isolation and you will not have to update your test if you later add them to your story. + -### 4. Render + {/* prettier-ignore-start */} -At this point, the story has been prepared and can be rendered. You pass it into the + -The story has been prepared and can be rendered. To render, you pass it into the rendering mechanism of your choice (e.g. Testing Library render function, Vue test utils mount function, etc). + {/* prettier-ignore-end */} -👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story is a renderable component that can be passed to your rendering mechanism. + ### 4. Render -### 5. Play + At this point, the story has been prepared and can be rendered. You pass it into the -**(optional)** + The story has been prepared and can be rendered. To render, you pass it into the rendering mechanism of your choice (e.g. Testing Library render function, Vue test utils mount function, etc). -Finally, stories can define a [play function](../essentials/interactions.md#play-function-for-interactions) to interact with the story and assert on details after it has rendered. In portable stories, the play function does not run automatically—you have to call it yourself. + 👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story is a renderable component that can be passed to your rendering mechanism. -👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story will return a `play` method to be called **after** it has rendered. + ### 5. Play -{/* prettier-ignore-start */} + **(optional)** - + Finally, stories can define a [play function](../essentials/interactions.md#play-function-for-interactions) to interact with the story and assert on details after it has rendered. In portable stories, the play function does not run automatically—you have to call it yourself. -{/* prettier-ignore-end */} + 👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story will return a `play` method to be called **after** it has rendered. - + {/* prettier-ignore-start */} -If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail. + - + {/* prettier-ignore-end */} -## Overriding globals + + If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail. + -If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story: + ## Overriding globals -{/* prettier-ignore-start */} + If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story: - + {/* prettier-ignore-start */} -{/* prettier-ignore-end */} + -{/* End supported renderers */} + {/* prettier-ignore-end */} + {/* End supported renderers */} diff --git a/docs/api/portable-stories-playwright.mdx b/docs/api/portable-stories-playwright.mdx index a801f53da80d..d3b92ab3093d 100644 --- a/docs/api/portable-stories-playwright.mdx +++ b/docs/api/portable-stories-playwright.mdx @@ -7,238 +7,208 @@ export const SUPPORTED_RENDERERS = ['react', 'vue']; (⚠️ **Experimental**) + + Portable stories are currently only supported in [React](?renderer=react) and [Vue](?renderer=vue) projects. + - - -Portable stories are currently only supported in [React](?renderer=react) and [Vue](?renderer=vue) projects. - - - -{/* End non-supported renderers */} - + {/* End non-supported renderers */} + + The portable stories API for Playwright CT is experimental. Playwright CT itself is also experimental. Breaking changes might occur in either library in upcoming releases. + - - -The portable stories API for Playwright CT is experimental. Playwright CT itself is also experimental. Breaking changes might occur in either library in upcoming releases. - - - -Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments, such as [Playwright Component Tests (CT)](https://playwright.dev/docs/test-components). - -Normally, Storybook composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Playwright CT, you can use the [`createTest`](#createtest) function, which extends Playwright's test functionality to add a custom `mount` mechanism, to take care of the story pipeline for you. - - - - - -Your project must be using React 18+ to use the portable stories API with Playwright CT. - -**Using `Next.js`?** The portable stories API is not yet supported in Next.js with Playwright CT. - -{/* **Using `Next.js`?** Next.js requires specific configuration that is only available in [Jest](./portable-stories-jest.md). The portable stories API is not supported in Next.js with Playwright CT. */} - - + Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments, such as [Playwright Component Tests (CT)](https://playwright.dev/docs/test-components). - - - - - - -If your stories use template-based Vue components, you may need to [alias the `vue` module](https://vuejs.org/guide/scaling-up/tooling#note-on-in-browser-template-compilation) to resolve correctly in the Playwright CT environment. You can do this via the [`ctViteConfig` property](https://playwright.dev/docs/test-components#i-have-a-project-that-already-uses-vite-can-i-reuse-the-config): - -

-Example Playwright configuration - -```ts -// playwright-config.ts -import { defineConfig } from '@playwright/experimental-ct-vue'; - -export default defineConfig({ - ctViteConfig: { - resolve: { - alias: { - vue: 'vue/dist/vue.esm-bundler.js', - }, - }, - }, -}); -``` - -
- - - - - -## createTest - -(⚠️ **Experimental**) + Normally, Storybook composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Playwright CT, you can use the [`createTest`](#createtest) function, which extends Playwright's test functionality to add a custom `mount` mechanism, to take care of the story pipeline for you. -Instead of using Playwright's own `test` function, you can use Storybook's special `createTest` function to [extend Playwright's base fixture](https://playwright.dev/docs/test-fixtures#creating-a-fixture) and override the `mount` function to load, render, and play the story. This function is experimental and is subject to changes. + + + Your project must be using React 18+ to use the portable stories API with Playwright CT. -{/* prettier-ignore-start */} + **Using `Next.js`?** The portable stories API is not yet supported in Next.js with Playwright CT. - + {/* **Using `Next.js`?** Next.js requires specific configuration that is only available in [Jest](./portable-stories-jest.md). The portable stories API is not supported in Next.js with Playwright CT. */} + + -{/* prettier-ignore-end */} + + + If your stories use template-based Vue components, you may need to [alias the `vue` module](https://vuejs.org/guide/scaling-up/tooling#note-on-in-browser-template-compilation) to resolve correctly in the Playwright CT environment. You can do this via the [`ctViteConfig` property](https://playwright.dev/docs/test-components#i-have-a-project-that-already-uses-vite-can-i-reuse-the-config): - +
+ Example Playwright configuration -The code which you write in your Playwright test file is transformed and orchestrated by Playwright, where part of the code executes in Node, while other parts execute in the browser. + ```ts + // playwright-config.ts + import { defineConfig } from '@playwright/experimental-ct-vue'; -Because of this, you have to compose the stories _in a separate file than your own test file_: + export default defineConfig({ + ctViteConfig: { + resolve: { + alias: { + vue: 'vue/dist/vue.esm-bundler.js', + }, + }, + }, + }); + ``` +
+ + -```ts -// Button.stories.portable.ts -// Replace with your renderer, e.g. react, vue3 -import { composeStories } from '@storybook/'; + ## createTest -import * as stories from './Button.stories'; + (⚠️ **Experimental**) -// This function will be executed in the browser -// and compose all stories, exporting them in a single object -export default composeStories(stories); -``` + Instead of using Playwright's own `test` function, you can use Storybook's special `createTest` function to [extend Playwright's base fixture](https://playwright.dev/docs/test-fixtures#creating-a-fixture) and override the `mount` function to load, render, and play the story. This function is experimental and is subject to changes. -You can then import the composed stories in your Playwright test file, as in the example above. + {/* prettier-ignore-start */} - + -### Type + {/* prettier-ignore-end */} -```ts -createTest( - baseTest: PlaywrightFixture -) => PlaywrightFixture -``` + + The code which you write in your Playwright test file is transformed and orchestrated by Playwright, where part of the code executes in Node, while other parts execute in the browser. -### Parameters + Because of this, you have to compose the stories *in a separate file than your own test file*: -#### `baseTest` + ```ts + // Button.stories.portable.ts + // Replace with your renderer, e.g. react, vue3 + import { composeStories } from '@storybook/'; -(**Required**) + import * as stories from './Button.stories'; -Type: `PlaywrightFixture` + // This function will be executed in the browser + // and compose all stories, exporting them in a single object + export default composeStories(stories); + ``` -The base test function to use, e.g. `test` from Playwright. + You can then import the composed stories in your Playwright test file, as in the example above. + -### Return + ### Type -Type: `PlaywrightFixture` + ```ts + createTest( + baseTest: PlaywrightFixture + ) => PlaywrightFixture + ``` -A Storybook-specific test function with the custom `mount` mechanism. + ### Parameters -## setProjectAnnotations + #### `baseTest` -This API should be called once, before the tests run, in [`playwright/index.ts`](https://playwright.dev/docs/test-components#step-1-install-playwright-test-for-components-for-your-respective-framework). This will make sure that when `mount` is called, the project annotations are taken into account as well. + (**Required**) -```ts -// playwright/index.ts -// Replace with your renderer, e.g. react, vue3 -import { setProjectAnnotations } from '@storybook/'; -import * as addonAnnotations from 'my-addon/preview'; -import * as previewAnnotations from '../.storybook/preview'; + Type: `PlaywrightFixture` -setProjectAnnotations([previewAnnotations, addonAnnotations]); -``` + The base test function to use, e.g. `test` from Playwright. - + ### Return -Sometimes a story can require an addon's [decorator](../writing-stories/decorators.md) or [loader](../writing-stories/loaders.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set. See `addonAnnotations` in the example above. + Type: `PlaywrightFixture` -Note: If the addon doesn't automatically apply the decorator or loader itself, but instead exports them for you to apply manually in `.storybook/preview.js|ts` (e.g. using `withThemeFromJSXProvider` from [@storybook/addon-themes](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider)), then you do not need to do anything else. They are already included in the `previewAnnotations` in the example above. + A Storybook-specific test function with the custom `mount` mechanism. - + ## setProjectAnnotations -### Type + This API should be called once, before the tests run, in [`playwright/index.ts`](https://playwright.dev/docs/test-components#step-1-install-playwright-test-for-components-for-your-respective-framework). This will make sure that when `mount` is called, the project annotations are taken into account as well. -```ts -(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void -``` + ```ts + // playwright/index.ts + // Replace with your renderer, e.g. react, vue3 + import { setProjectAnnotations } from '@storybook/'; + import * as addonAnnotations from 'my-addon/preview'; + import * as previewAnnotations from '../.storybook/preview'; -### Parameters + setProjectAnnotations([previewAnnotations, addonAnnotations]); + ``` -#### `projectAnnotations` + + Sometimes a story can require an addon's [decorator](../writing-stories/decorators.md) or [loader](../writing-stories/loaders.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set. See `addonAnnotations` in the example above. -(**Required**) + Note: If the addon doesn't automatically apply the decorator or loader itself, but instead exports them for you to apply manually in `.storybook/preview.js|ts` (e.g. using `withThemeFromJSXProvider` from [@storybook/addon-themes](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider)), then you do not need to do anything else. They are already included in the `previewAnnotations` in the example above. + -Type: `ProjectAnnotation | ProjectAnnotation[]` + ### Type -A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories. + ```ts + (projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void + ``` -## Annotations + ### Parameters -Annotations are the metadata applied to a story, like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project. + #### `projectAnnotations` - + (**Required**) -[Read more about Playwright's component testing](https://playwright.dev/docs/test-components#test-stories). + Type: `ProjectAnnotation | ProjectAnnotation[]` - + A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories. -## Story pipeline + ## Annotations -To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline: + Annotations are the metadata applied to a story, like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project. -![A flow diagram of the story pipeline. First, set project annotations. Storybook automatically collects decorators etc. which are exported by addons and the .storybook/preview file. .storybook/preview.js produces project annotations; some-addon/preview produces addon annotations. The rest of the steps are labeled as a group, Playwright test. Second, prepare. Storybook gathers all the metadata required for a story to be composed. Select.stories.js produces component annotations from the default export and story annotations from the named export. Third, load. Storybook executes all loaders (async). Fourth, render. Storybook renders the story as a component. Illustration of the rendered Select component. Fifth, play. Storybook runs the play function (interacting with component). Illustration of the renderer Select component, now open.](story-pipeline-playwright-ct.png) + + [Read more about Playwright's component testing](https://playwright.dev/docs/test-components#test-stories). + -When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment: + ## Story pipeline -### 1. Apply project-level annotations + To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline: -[Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotatations are those defined in your `.storybook/preview.js` file and by addons you're using. In portable stories, these annotations are not applied automatically—you must apply them yourself. + ![A flow diagram of the story pipeline. First, set project annotations. Storybook automatically collects decorators etc. which are exported by addons and the .storybook/preview file. .storybook/preview.js produces project annotations; some-addon/preview produces addon annotations. The rest of the steps are labeled as a group, Playwright test. Second, prepare. Storybook gathers all the metadata required for a story to be composed. Select.stories.js produces component annotations from the default export and story annotations from the named export. Third, load. Storybook executes all loaders (async). Fourth, render. Storybook renders the story as a component. Illustration of the rendered Select component. Fifth, play. Storybook runs the play function (interacting with component). Illustration of the renderer Select component, now open.](story-pipeline-playwright-ct.png) -👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API. + When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment: -### 2. Prepare, load, render, and play + ### 1. Apply project-level annotations -The story pipeline includes preparing the story, [loading data](../writing-stories/loaders.md), rendering the story, and [playing interactions](../essentials/interactions.md#play-function-for-interactions). In portable stories within Playwright CT, the `mount` function takes care of these steps for you. + [Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotatations are those defined in your `.storybook/preview.js` file and by addons you're using. In portable stories, these annotations are not applied automatically—you must apply them yourself. -👉 For this, you use the [`createTest`](#createtest) API. + 👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API. - + ### 2. Prepare, load, render, and play -If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail. + The story pipeline includes preparing the story, [loading data](../writing-stories/loaders.md), rendering the story, and [playing interactions](../essentials/interactions.md#play-function-for-interactions). In portable stories within Playwright CT, the `mount` function takes care of these steps for you. - + 👉 For this, you use the [`createTest`](#createtest) API. -## Overriding globals + + If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail. + -If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story: + ## Overriding globals -{/* prettier-ignore-start */} + If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story: -```tsx -// Button.portable.ts -import { test } from 'playwright'; -import { render } from '@testing-library/react'; -import { composeStory } from '@storybook/react'; + {/* prettier-ignore-start */} -import meta, { Primary } from './Button.stories'; + ```tsx + // Button.portable.ts + import { test } from 'playwright'; + import { render } from '@testing-library/react'; + import { composeStory } from '@storybook/react'; -export const PrimaryEnglish = composeStory( - Primary, - meta, - { globals: { locale: 'en' } } // 👈 Project annotations to override the locale -); + import meta, { Primary } from './Button.stories'; -export const PrimarySpanish = - composeStory(Primary, meta, { globals: { locale: 'es' } }); -``` + export const PrimaryEnglish = composeStory( + Primary, + meta, + { globals: { locale: 'en' } } // 👈 Project annotations to override the locale + ); -You can then use those composed stories in your Playwright test file using the [`createTest`](#createtest) function. + export const PrimarySpanish = + composeStory(Primary, meta, { globals: { locale: 'es' } }); + ``` -{/* prettier-ignore-end */} + You can then use those composed stories in your Playwright test file using the [`createTest`](#createtest) function. -{/* End supported renderers */} + {/* prettier-ignore-end */} + {/* End supported renderers */} diff --git a/docs/api/portable-stories-vitest.mdx b/docs/api/portable-stories-vitest.mdx index 96018f5a46a4..ff21c16abc6e 100644 --- a/docs/api/portable-stories-vitest.mdx +++ b/docs/api/portable-stories-vitest.mdx @@ -7,313 +7,267 @@ title: 'Portable stories in Vitest' export const SUPPORTED_RENDERERS = ['react', 'vue', 'svelte']; + + Portable stories in Vitest are currently only supported in [React](?renderer=react), [Vue](?renderer=vue) and [Svelte](?renderer=svelte) projects. + - - -Portable stories in Vitest are currently only supported in [React](?renderer=react), [Vue](?renderer=vue) and [Svelte](?renderer=svelte) projects. - - - -{/* End non-supported renderers */} - + {/* End non-supported renderers */} + Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments, such as [Vitest](https://vitest.dev). -Portable stories are Storybook [stories](../writing-stories/index.md) which can be used in external environments, such as [Vitest](https://vitest.dev). - -Normally, Storybook composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Vitest tests, you must handle the story pipeline yourself, which is what the [`composeStories`](#composestories) and [`composeStory`](#composestory) functions enable. + Normally, Storybook composes a story and its [annotations](#annotations) automatically, as part of the [story pipeline](#story-pipeline). When using stories in Vitest tests, you must handle the story pipeline yourself, which is what the [`composeStories`](#composestories) and [`composeStory`](#composestory) functions enable. - - - - -**Using `Next.js`?** Next.js requires specific configuration that is only available in [Jest](./portable-stories-jest.md). The portable stories API is not supported in Next.js with Vitest. - - - - + + + **Using `Next.js`?** Next.js requires specific configuration that is only available in [Jest](./portable-stories-jest.md). The portable stories API is not supported in Next.js with Vitest. + + -## composeStories - -`composeStories` will process the component's stories you specify, compose each of them with the necessary [annotations](#annotations), and return an object containing the composed stories. - - - -By default, the composed story will render the component with the [args](../writing-stories/args.md) that are defined in the story. You can also pass any props to the component in your test and those props will override the values passed in the story's args. - - - - - -By default, the composed story will render the component with the [args](../writing-stories/args.md) that are defined in the story. If you need to override props for an individual story, you can use the [`composeStory`](#composestory) function to do so. - - + ## composeStories -{/* prettier-ignore-start */} + `composeStories` will process the component's stories you specify, compose each of them with the necessary [annotations](#annotations), and return an object containing the composed stories. - + + By default, the composed story will render the component with the [args](../writing-stories/args.md) that are defined in the story. You can also pass any props to the component in your test and those props will override the values passed in the story's args. + -{/* prettier-ignore-end */} + + By default, the composed story will render the component with the [args](../writing-stories/args.md) that are defined in the story. If you need to override props for an individual story, you can use the [`composeStory`](#composestory) function to do so. + -### Type + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} -```ts -( - csfExports: CSF file exports, - projectAnnotations?: ProjectAnnotations -) => Record -``` -{/* prettier-ignore-end */} + -### Parameters + {/* prettier-ignore-end */} -#### `csfExports` + ### Type -(**Required**) + {/* prettier-ignore-start */} -Type: CSF file exports + ```ts + ( + csfExports: CSF file exports, + projectAnnotations?: ProjectAnnotations + ) => Record + ``` -Specifies which component's stories you want to compose. Pass the **full set of exports** from the CSF file (not the default export!). E.g. `import * as stories from './Button.stories'` + {/* prettier-ignore-end */} -#### `projectAnnotations` + ### Parameters -Type: `ProjectAnnotation | ProjectAnnotation[]` + #### `csfExports` -Specifies the project annotations to be applied to the composed stories. + (**Required**) -This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter. + Type: CSF file exports -This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`. + Specifies which component's stories you want to compose. Pass the **full set of exports** from the CSF file (not the default export!). E.g. `import * as stories from './Button.stories'` -### Return + #### `projectAnnotations` -Type: `Record` + Type: `ProjectAnnotation | ProjectAnnotation[]` -An object where the keys are the names of the stories and the values are the composed stories. + Specifies the project annotations to be applied to the composed stories. -Additionally, the composed story will have the following properties: + This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter. -| Property | Type | Description | -| ---------- | ----------------------------------------- | ------------------------------------------------------------------------------------- | -| storyName | `string` | The story's name | -| args | `Record` | The story's [args](../writing-stories/args.md) | -| argTypes | `ArgType` | The story's [argTypes](./arg-types.md) | -| id | `string` | The story's id | -| parameters | `Record` | The story's [parameters](./parameters.md) | -| load | `() => Promise` | [Prepares](#3-prepare) the story for rendering and and cleans up all previous stories | -| play | `(context) => Promise \| undefined` | Executes the [play function](#5-play) of a given story | + This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`. -## composeStory + ### Return -You can use `composeStory` if you wish to compose a single story for a component. + Type: `Record` -{/* prettier-ignore-start */} + An object where the keys are the names of the stories and the values are the composed stories. - + Additionally, the composed story will have the following properties: -{/* prettier-ignore-end */} + | Property | Type | Description | + | ---------- | ----------------------------------------- | ------------------------------------------------------------------------------------- | + | storyName | `string` | The story's name | + | args | `Record` | The story's [args](../writing-stories/args.md) | + | argTypes | `ArgType` | The story's [argTypes](./arg-types.md) | + | id | `string` | The story's id | + | parameters | `Record` | The story's [parameters](./parameters.md) | + | load | `() => Promise` | [Prepares](#3-prepare) the story for rendering and and cleans up all previous stories | + | play | `(context) => Promise \| undefined` | Executes the [play function](#5-play) of a given story | -### Type + ## composeStory -{/* prettier-ignore-start */} -```ts -( - story: Story export, - componentAnnotations: Meta, - projectAnnotations?: ProjectAnnotations, - exportsName?: string -) => ComposedStoryFn -``` -{/* prettier-ignore-end */} + You can use `composeStory` if you wish to compose a single story for a component. -### Parameters + {/* prettier-ignore-start */} -#### `story` + -(**Required**) + {/* prettier-ignore-end */} -Type: `Story export` + ### Type -Specifies which story you want to compose. + {/* prettier-ignore-start */} -#### `componentAnnotations` + ```ts + ( + story: Story export, + componentAnnotations: Meta, + projectAnnotations?: ProjectAnnotations, + exportsName?: string + ) => ComposedStoryFn + ``` -(**Required**) + {/* prettier-ignore-end */} -Type: `Meta` + ### Parameters -The default export from the stories file containing the [`story`](#story). + #### `story` -#### `projectAnnotations` + (**Required**) -Type: `ProjectAnnotation | ProjectAnnotation[]` + Type: `Story export` -Specifies the project annotations to be applied to the composed story. + Specifies which story you want to compose. -This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter. + #### `componentAnnotations` -This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`. + (**Required**) -#### `exportsName` + Type: `Meta` -Type: `string` + The default export from the stories file containing the [`story`](#story). -You probably don't need this. Because `composeStory` accepts a single story, it does not have access to the name of that story's export in the file (like `composeStories` does). If you must ensure unique story names in your tests and you cannot use `composeStories`, you can pass the name of the story's export here. + #### `projectAnnotations` -### Return + Type: `ProjectAnnotation | ProjectAnnotation[]` -Type: `ComposedStoryFn` + Specifies the project annotations to be applied to the composed story. -A single [composed story](#return). + This parameter is provided for convenience. You should likely use [`setProjectAnnotations`](#setprojectannotations) instead. Details about the `ProjectAnnotation` type can be found in that function's [`projectAnnotations`](#projectannotations-2) parameter. -## setProjectAnnotations + This parameter can be used to [override](#overriding-globals) the project annotations applied via `setProjectAnnotations`. -This API should be called once, before the tests run, typically in a [setup file](https://vitest.dev/config/#setupfiles). This will make sure that whenever `composeStories` or `composeStory` are called, the project annotations are taken into account as well. + #### `exportsName` -```ts -// setup-portable-stories.ts -// Replace with your renderer, e.g. react, vue3, svelte -import { setProjectAnnotations } from '@storybook/'; -import * as addonAnnotations from 'my-addon/preview'; -import * as previewAnnotations from './.storybook/preview'; + Type: `string` -setProjectAnnotations([previewAnnotations, addonAnnotations]); -``` + You probably don't need this. Because `composeStory` accepts a single story, it does not have access to the name of that story's export in the file (like `composeStories` does). If you must ensure unique story names in your tests and you cannot use `composeStories`, you can pass the name of the story's export here. - + ### Return -Sometimes a story can require an addon's [decorator](../writing-stories/decorators.md) or [loader](../writing-stories/loaders.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set. See `addonAnnotations` in the example above. + Type: `ComposedStoryFn` -Note: If the addon doesn't automatically apply the decorator or loader itself, but instead exports them for you to apply manually in `.storybook/preview.js|ts` (e.g. using `withThemeFromJSXProvider` from [@storybook/addon-themes](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider)), then you do not need to do anything else. They are already included in the `previewAnnotations` in the example above. + A single [composed story](#return). - + ## setProjectAnnotations -### Type + This API should be called once, before the tests run, typically in a [setup file](https://vitest.dev/config/#setupfiles). This will make sure that whenever `composeStories` or `composeStory` are called, the project annotations are taken into account as well. -```ts -(projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void -``` + ```ts + // setup-portable-stories.ts + // Replace with your renderer, e.g. react, vue3, svelte + import { setProjectAnnotations } from '@storybook/'; + import * as addonAnnotations from 'my-addon/preview'; + import * as previewAnnotations from './.storybook/preview'; -### Parameters + setProjectAnnotations([previewAnnotations, addonAnnotations]); + ``` -#### `projectAnnotations` + + Sometimes a story can require an addon's [decorator](../writing-stories/decorators.md) or [loader](../writing-stories/loaders.md) to render properly. For example, an addon can apply a decorator that wraps your story in the necessary router context. In this case, you must include that addon's `preview` export in the project annotations set. See `addonAnnotations` in the example above. -(**Required**) + Note: If the addon doesn't automatically apply the decorator or loader itself, but instead exports them for you to apply manually in `.storybook/preview.js|ts` (e.g. using `withThemeFromJSXProvider` from [@storybook/addon-themes](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider)), then you do not need to do anything else. They are already included in the `previewAnnotations` in the example above. + -Type: `ProjectAnnotation | ProjectAnnotation[]` + ### Type -A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories. + ```ts + (projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => void + ``` -## Annotations + ### Parameters -Annotations are the metadata applied to a story, like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project. + #### `projectAnnotations` -## Story pipeline + (**Required**) -To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline: + Type: `ProjectAnnotation | ProjectAnnotation[]` -![A flow diagram of the story pipeline. First, set project annotations. Storybook automatically collects decorators etc. which are exported by addons and the .storybook/preview file. .storybook/preview.js produces project annotations; some-addon/preview produces addon annotations. Second, prepare. Storybook gathers all the metadata required for a story to be composed. Select.stories.js produces component annotations from the default export and story annotations from the named export. Third, load. Storybook executes all loaders (async). Fourth, render. Storybook renders the story as a component. Illustration of the rendered Select component. Fifth, play. Storybook runs the play function (interacting with component). Illustration of the renderer Select component, now open.](story-pipeline.png) + A set of project [annotations](#annotations) (those defined in `.storybook/preview.js|ts`) or an array of sets of project annotations, which will be applied to all composed stories. -When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment: + ## Annotations -### 1. Apply project-level annotations + Annotations are the metadata applied to a story, like [args](../writing-stories/args.md), [decorators](../writing-stories/decorators.md), [loaders](../writing-stories/loaders.md), and [play functions](../writing-stories/play-function.md). They can be defined for a specific story, all stories for a component, or all stories in the project. -[Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotatations are those defined in your `.storybook/preview.js` file and by addons you're using. In portable stories, these annotations are not applied automatically—you must apply them yourself. + ## Story pipeline -👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API. + To preview your stories, Storybook runs a story pipeline, which includes applying project annotations, loading data, rendering the story, and playing interactions. This is a simplified version of the pipeline: -### 2. Compose + ![A flow diagram of the story pipeline. First, set project annotations. Storybook automatically collects decorators etc. which are exported by addons and the .storybook/preview file. .storybook/preview.js produces project annotations; some-addon/preview produces addon annotations. Second, prepare. Storybook gathers all the metadata required for a story to be composed. Select.stories.js produces component annotations from the default export and story annotations from the named export. Third, load. Storybook executes all loaders (async). Fourth, render. Storybook renders the story as a component. Illustration of the rendered Select component. Fifth, play. Storybook runs the play function (interacting with component). Illustration of the renderer Select component, now open.](story-pipeline.png) -The story is prepared by running [`composeStories`](#composestories) or [`composeStory`](#composestory). You do not need to do anything for this step. + When you want to reuse a story in a different environment, however, it's crucial to understand that all these steps make a story. The portable stories API provides you with the mechanism to recreate that story pipeline in your external environment: -### 3. Prepare + ### 1. Apply project-level annotations -Stories can prepare data they need (e.g. setting up some mocks or fetching data) before rendering by defining [loaders](../writing-stories/loaders.md) or [beforeEach](../writing-tests/interaction-testing.md#run-code-before-each-test). In portable stories, loaders and beforeEach are not applied automatically — you have to apply them yourself. + [Annotations](#annotations) come from the story itself, that story's component, and the project. The project-level annotatations are those defined in your `.storybook/preview.js` file and by addons you're using. In portable stories, these annotations are not applied automatically—you must apply them yourself. -👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed story will return a `load` method to be called **before** it is rendered. + 👉 For this, you use the [`setProjectAnnotations`](#setprojectannotations) API. - + ### 2. Compose -It is recommended to always run `load` before rendering, even if the story doesn't have any loaders or beforeEach applied. By doing so, you ensure that the tests are cleaned up properly to maintain isolation and you will not have to update your test if you later add them to your story. + The story is prepared by running [`composeStories`](#composestories) or [`composeStory`](#composestory). You do not need to do anything for this step. - + ### 3. Prepare -{/* prettier-ignore-start */} + Stories can prepare data they need (e.g. setting up some mocks or fetching data) before rendering by defining [loaders](../writing-stories/loaders.md) or [beforeEach](../writing-tests/interaction-testing.md#run-code-before-each-test). In portable stories, loaders and beforeEach are not applied automatically — you have to apply them yourself. - + 👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed story will return a `load` method to be called **before** it is rendered. -{/* prettier-ignore-end */} + + It is recommended to always run `load` before rendering, even if the story doesn't have any loaders or beforeEach applied. By doing so, you ensure that the tests are cleaned up properly to maintain isolation and you will not have to update your test if you later add them to your story. + -### 4. Render + {/* prettier-ignore-start */} -At this point, the story has been prepared and can be rendered. You pass it into the + -The story has been prepared and can be rendered. To render, you pass it into the rendering mechanism of your choice (e.g. Testing Library render function, Vue test utils mount function, etc). + {/* prettier-ignore-end */} -👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story is a renderable component that can be passed to your rendering mechanism. + ### 4. Render -### 5. Play + At this point, the story has been prepared and can be rendered. You pass it into the -**(optional)** + The story has been prepared and can be rendered. To render, you pass it into the rendering mechanism of your choice (e.g. Testing Library render function, Vue test utils mount function, etc). -Finally, stories can define a [play function](../essentials/interactions.md#play-function-for-interactions) to interact with the story and assert on details after it has rendered. In portable stories, the play function does not run automatically—you have to call it yourself. + 👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story is a renderable component that can be passed to your rendering mechanism. -👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story will return a `play` method to be called **after** it has rendered. + ### 5. Play -{/* prettier-ignore-start */} + **(optional)** - + Finally, stories can define a [play function](../essentials/interactions.md#play-function-for-interactions) to interact with the story and assert on details after it has rendered. In portable stories, the play function does not run automatically—you have to call it yourself. -{/* prettier-ignore-end */} + 👉 For this, you use the [`composeStories`](#composestories) or [`composeStory`](#composestory) API. The composed Story will return a `play` method to be called **after** it has rendered. - + {/* prettier-ignore-start */} -If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail. + - + {/* prettier-ignore-end */} -## Overriding globals + + If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail. + -If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story: + ## Overriding globals -{/* prettier-ignore-start */} + If your stories behave differently based on [globals](../essentials/toolbars-and-globals.md#globals) (e.g. rendering text in English or Spanish), you can define those global values in portable stories by overriding project annotations when composing a story: - + {/* prettier-ignore-start */} -{/* prettier-ignore-end */} + -{/* End supported renderers */} + {/* prettier-ignore-end */} + {/* End supported renderers */} diff --git a/docs/api/stories.mdx b/docs/api/stories.mdx index 734bcb78dd58..b5d7ca352d51 100644 --- a/docs/api/stories.mdx +++ b/docs/api/stories.mdx @@ -6,6 +6,6 @@ Storybook is extremely customizable and offers various ways to write your storie Check the links below to learn more about it: -- [Component Story Format (CSF)](./csf.md), the recommended way for you to write your stories. -- [MDX](./mdx.md), to create not only stories but also your own custom documentation. -- [`ArgTypes`](./argtypes.md), to learn how you can extend your component's stories. +* [Component Story Format (CSF)](./csf.md), the recommended way for you to write your stories. +* [MDX](./mdx.md), to create not only stories but also your own custom documentation. +* [`ArgTypes`](./argtypes.md), to learn how you can extend your component's stories. diff --git a/docs/builders/builder-api.mdx b/docs/builders/builder-api.mdx index e4e030974cd6..a24340e3c4dc 100644 --- a/docs/builders/builder-api.mdx +++ b/docs/builders/builder-api.mdx @@ -14,23 +14,13 @@ To opt into a builder, the user must add it as a dependency and then edit their {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -40,11 +30,7 @@ In Storybook, every builder must implement the following [API](https://github.co {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -67,11 +53,7 @@ By default, Storybook's configuration is handled in a dedicated file (`storybook {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -81,11 +63,7 @@ The [`preview.js`](../configure/index.md#configure-story-rendering) configuratio {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -95,11 +73,7 @@ The [`preview.js`](../configure/index.md#configure-story-rendering) configuratio {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -113,11 +87,7 @@ One of Storybook's core features it's the ability to generate a static build tha {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -127,11 +97,7 @@ By default, when Storybook starts in development mode, it relies on its internal {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -141,11 +107,7 @@ The builder must provide a way to stop the development server once the process t {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -159,6 +121,6 @@ This area is under rapid development, and the associated documentation is still **Learn more about builders** -- [Vite builder](./vite.md) for bundling with Vite -- [Webpack builder](./webpack.md) for bundling with Webpack -- Builder API for building a Storybook builder +* [Vite builder](./vite.md) for bundling with Vite +* [Webpack builder](./webpack.md) for bundling with Webpack +* Builder API for building a Storybook builder diff --git a/docs/builders/index.mdx b/docs/builders/index.mdx index ed1309da02cb..14235094dee2 100644 --- a/docs/builders/index.mdx +++ b/docs/builders/index.mdx @@ -21,5 +21,5 @@ npx storybook@latest init --builder Storybook uses the Webpack 5 builder by default if you don't specify one. If you want to use a different builder in your application, these docs detail how you can set up Storybook's supported builders. -- [**Vite builder**](./vite.md) for bundling your stories with Vite with near-instant HMR. -- [**Webpack**](./webpack.md) for bundling your stories with Webpack with improved performance +* [**Vite builder**](./vite.md) for bundling your stories with Vite with near-instant HMR. +* [**Webpack**](./webpack.md) for bundling your stories with Webpack with improved performance diff --git a/docs/builders/vite.mdx b/docs/builders/vite.mdx index c59fafbb4a69..1b7d65cd8560 100644 --- a/docs/builders/vite.mdx +++ b/docs/builders/vite.mdx @@ -4,8 +4,8 @@ title: 'Vite' Storybook Vite builder bundles your components and stories with [Vite](https://vitejs.dev/), a fast ESM bundler. -- For applications built with Vite: it allows reusing the existing configuration in Storybook. -- For applications built with Webpack: it provides faster startup and refresh times, with the disadvantage that your component's execution environment differs from your application. +* For applications built with Vite: it allows reusing the existing configuration in Storybook. +* For applications built with Webpack: it provides faster startup and refresh times, with the disadvantage that your component's execution environment differs from your application. ## Setup @@ -15,13 +15,7 @@ Run the following command to install the builder. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -29,11 +23,7 @@ Update your Storybook configuration (in `.storybook/main.js|ts`) to include the {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -45,11 +35,7 @@ When Storybook loads, it automatically merges the configuration into its own. Ho {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -61,11 +47,7 @@ If you need to customize the builder's configuration and apply specific options {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -75,18 +57,12 @@ By default, the Vite builder in Storybook searches for the Vite configuration fi {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -If you do not want Storybook to load the Vite configuration file automatically, you can use the `viteConfigPath` option to point to a non-existent file. - + If you do not want Storybook to load the Vite configuration file automatically, you can use the `viteConfigPath` option to point to a non-existent file. ### TypeScript @@ -95,15 +71,11 @@ If you need, you can also configure Storybook's Vite builder using TypeScript. R {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} ---- +*** ## Troubleshooting @@ -118,11 +90,7 @@ Currently, [automatic argType inference](../api/arg-types.md#automatic-argtype-i {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -132,16 +100,12 @@ If you are migrating from a Webpack-based project, such as [CRA](https://create- {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} **Learn more about builders** -- Vite builder for bundling with Vite -- [Webpack builder](./webpack.md) for bundling with Webpack -- [Builder API](./builder-api.md) for building a Storybook builder +* Vite builder for bundling with Vite +* [Webpack builder](./webpack.md) for bundling with Webpack +* [Builder API](./builder-api.md) for building a Storybook builder diff --git a/docs/builders/webpack.mdx b/docs/builders/webpack.mdx index 67528a29f858..0619f252a274 100644 --- a/docs/builders/webpack.mdx +++ b/docs/builders/webpack.mdx @@ -10,17 +10,12 @@ By default, Storybook provides zero-config support for Webpack and automatically | Option | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `lazyCompilation` | Enables Webpack's experimental [`lazy compilation`](https://webpack.js.org/configuration/experiments/#experimentslazycompilation)
`core: { builder: { options: { lazyCompilation: true } } }` | -| `fsCache` | Configures Webpack's filesystem [caching](https://webpack.js.org/configuration/cache/#cachetype) feature
`core: { builder: { options: { fsCache: true } } }` | +| `lazyCompilation` | Enables Webpack's experimental [`lazy compilation`](https://webpack.js.org/configuration/experiments/#experimentslazycompilation)
`core: { builder: { options: { lazyCompilation: true } } }` | +| `fsCache` | Configures Webpack's filesystem [caching](https://webpack.js.org/configuration/cache/#cachetype) feature
`core: { builder: { options: { fsCache: true } } }` | {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -30,12 +25,7 @@ Storybook's Webpack configuration is based on [Webpack 5](https://webpack.js.org {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -47,12 +37,7 @@ Another way to customize your Storybook configuration is to add a custom plugin {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -64,19 +49,12 @@ If you already have an existing Webpack configuration file that you need to reus {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -Projects scaffolded based on generators may require that you import their specific Webpack configuration files. We suggest reading your generator's documentation for more information. - + Projects scaffolded based on generators may require that you import their specific Webpack configuration files. We suggest reading your generator's documentation for more information. ### Debug Webpack configuration @@ -85,12 +63,7 @@ If you intend to debug the Webpack configuration used by Storybook, you can use {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -98,12 +71,7 @@ Additionally, if you're generating a [static build](../api/cli-options.md#build) {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -117,20 +85,12 @@ If your project is built using [SWC](https://swc.rs/), use the [`@storybook/addo {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -Additional options can be provided to customize the SWC configuration. See the [SWC API documentation](../api/main-config-swc.md) for more information. - + Additional options can be provided to customize the SWC configuration. See the [SWC API documentation](../api/main-config-swc.md) for more information. When enabled, this addon adjusts the Webpack configuration to use the [`swc-loader`](https://swc.rs/docs/usage/swc-loader) for JavaScript and TypeScript files. Additionally, it will detect and use your project's SWC configuration. @@ -141,20 +101,12 @@ If you're working with a project that relies on Babel's tooling to provide suppo {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -Additional options can be provided to customize the Babel configuration. See the [`babel` API documentation](../api/main-config-babel.md) for more information, or if you're working on an addon, the [`babelDefault` documentation](../api/main-config-babel-default.md) for more information. - + Additional options can be provided to customize the Babel configuration. See the [`babel` API documentation](../api/main-config-babel.md) for more information, or if you're working on an addon, the [`babelDefault` documentation](../api/main-config-babel-default.md) for more information. When enabled, the addon will adjust the Webpack configuration to use the [`babel-loader`](https://webpack.js.org/loaders/babel-loader/) as the default loader for JavaScript and TypeScript files. Additionally, it will detect and use your project's Babel configuration. @@ -167,12 +119,7 @@ Storybook's default Webpack configuration provides support for most project setu {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -180,12 +127,7 @@ However, if you're working with a framework that provides a default aliasing con {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -199,6 +141,6 @@ Support for Webpack 4 has been removed and is no longer being maintained. If you **Learn more about builders** -- [Vite builder](./vite.md) for bundling with Vite -- Webpack builder for bundling with Webpack -- [Builder API](./builder-api.md) for building a Storybook builder +* [Vite builder](./vite.md) for bundling with Vite +* Webpack builder for bundling with Webpack +* [Builder API](./builder-api.md) for building a Storybook builder diff --git a/docs/configure/compilers.mdx b/docs/configure/compilers.mdx index 81205df3f97f..b06739ea41b9 100644 --- a/docs/configure/compilers.mdx +++ b/docs/configure/compilers.mdx @@ -9,9 +9,7 @@ Javascript compilers are essential in optimizing and transforming code, enhancin SWC is a fast, highly extensible tool for compiling and bundling modern JavaScript applications. Powered by [Rust](https://www.rust-lang.org/), it improves performance and reduces build times. Storybook includes a built-in integration with SWC, allowing zero-configuration setup and built-in types for APIs. If you've initialized Storybook in a Webpack-based project with any of the supported [frameworks](./frameworks.md), except Angular, Create React App, Ember.js and Next.js, it will automatically use SWC as its default, providing you with faster loading time. - -Support for the SWC builder is currently experimental for Next.js projects, and it's not enabled by default. It requires you to opt in to use it. For more information on configuring SWC with the supported frameworks, see the [SWC API](../api/main-config-swc.md) documentation. - + Support for the SWC builder is currently experimental for Next.js projects, and it's not enabled by default. It requires you to opt in to use it. For more information on configuring SWC with the supported frameworks, see the [SWC API](../api/main-config-swc.md) documentation. ## Babel @@ -19,24 +17,20 @@ Support for the SWC builder is currently experimental for Next.js projects, and Babel is a widely adopted JavaScript compiler providing a modular architecture and extensive plugin system to support a wide range of use cases, enabling access to the cutting-edge features of the tooling ecosystem. Storybook provides a seamless integration with Babel, allowing you to share a standard setup between your project and Storybook without any additional configuration. - -If you're not using Storybook 7, please reference the [previous documentation](../../../release-6-5/docs/configure/babel.md) for guidance on configuring your Babel setup. - + If you're not using Storybook 7, please reference the [previous documentation](../../../release-6-5/docs/configure/babel.md) for guidance on configuring your Babel setup. ### Configure By default, Babel provides an opinionated [configuration](https://babeljs.io/docs/config-files) that works for most projects, relying on two distinct methods for configuring projects with the tool: -- **Project-wide configuration**: Babel will look for a `babel.config.js` or equivalent file in the root of your project and use it to configure your project's Babel setup. -- **File-relative configuration**: Babel will look for a `.babelrc.json` or equivalent file, introspecting the project structure until it finds a configuration file. This will allow you to configure Babel individually for multiple aspects of your project. +* **Project-wide configuration**: Babel will look for a `babel.config.js` or equivalent file in the root of your project and use it to configure your project's Babel setup. +* **File-relative configuration**: Babel will look for a `.babelrc.json` or equivalent file, introspecting the project structure until it finds a configuration file. This will allow you to configure Babel individually for multiple aspects of your project. Storybook relies on an agnostic approach to configuring Babel, enabling you to provide the necessary configuration for your project, and it will use it. Based on the supported frameworks, builders, and addons, it may include minor adjustments to ensure compatibility with Storybook's features. - -For custom project configurations such as monorepos, where you have multiple Storybook configurations, creating a `.babelrc.json` file in your project's current working directory may not be sufficient. In those cases, you can create a `babel.config.js` file to override Babel's configuration, and Storybook will automatically detect and use it. See the Babel [documentation](https://babeljs.io/docs/config-files) for more information. - + For custom project configurations such as monorepos, where you have multiple Storybook configurations, creating a `.babelrc.json` file in your project's current working directory may not be sufficient. In those cases, you can create a `babel.config.js` file to override Babel's configuration, and Storybook will automatically detect and use it. See the Babel [documentation](https://babeljs.io/docs/config-files) for more information. ### Working with Create React App @@ -45,23 +39,16 @@ If you're working with a project that was initialized with [Create React App](ht ## Troubleshooting - - -### The SWC compiler doesn't work with React - -If you have enabled the SWC builder option in a React-based project and you are not explicitly importing React in your `jsx|tsx` files, it can cause Storybook to fail to load. SWC does not automatically import the `jsx-runtime` module when using the SWC builder. To resolve this issue, you need to adjust your Storybook configuration file (i.e., `.storybook/main.js|ts`) and configure the `swc` option as follows: + + ### The SWC compiler doesn't work with React -{/* prettier-ignore-start */} + If you have enabled the SWC builder option in a React-based project and you are not explicitly importing React in your `jsx|tsx` files, it can cause Storybook to fail to load. SWC does not automatically import the `jsx-runtime` module when using the SWC builder. To resolve this issue, you need to adjust your Storybook configuration file (i.e., `.storybook/main.js|ts`) and configure the `swc` option as follows: - + {/* prettier-ignore-start */} -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} ### Babel configuration not working diff --git a/docs/configure/environment-variables.mdx b/docs/configure/environment-variables.mdx index 653fdd0f70f7..3ce385d82d8a 100644 --- a/docs/configure/environment-variables.mdx +++ b/docs/configure/environment-variables.mdx @@ -10,38 +10,23 @@ STORYBOOK_THEME=red STORYBOOK_DATA_KEY=12345 npm run storybook ``` - -Do not store any secrets (e.g., private API keys) or other types of sensitive information in your Storybook. Environment variables are embedded into the build, meaning anyone can view them by inspecting your files. - + Do not store any secrets (e.g., private API keys) or other types of sensitive information in your Storybook. Environment variables are embedded into the build, meaning anyone can view them by inspecting your files. Then we can access these environment variables anywhere inside our preview JavaScript code like below: + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} - - - + {/* prettier-ignore-end */} + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} - - - + {/* prettier-ignore-end */} @@ -49,9 +34,7 @@ Then we can access these environment variables anywhere inside our preview JavaS You can also access these variables in your custom ``/`` using the substitution `%STORYBOOK_X%`, for example: `%STORYBOOK_THEME%` will become `red`. - -If using the environment variables as attributes or values in JavaScript, you may need to add quotes, as the value will be inserted directly, for example: ``. - + If using the environment variables as attributes or values in JavaScript, you may need to add quotes, as the value will be inserted directly, for example: ``. ### Using .env files @@ -66,43 +49,24 @@ Then you can access this environment variable anywhere, even within your stories {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} + #### With Vite -#### With Vite - -Out of the box, Storybook provides a [Vite builder](../builders/vite.md), which does not output Node.js globals like `process.env`. To access environment variables in Storybook (e.g., `STORYBOOK_`, `VITE_`), you can use `import.meta.env`. For example: + Out of the box, Storybook provides a [Vite builder](../builders/vite.md), which does not output Node.js globals like `process.env`. To access environment variables in Storybook (e.g., `STORYBOOK_`, `VITE_`), you can use `import.meta.env`. For example: -{/* prettier-ignore-start */} + {/* prettier-ignore-start */} - - -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} - -You can also use specific files for specific modes. Add a `.env.development` or `.env.production` to apply different values to your environment variables. - + You can also use specific files for specific modes. Add a `.env.development` or `.env.production` to apply different values to your environment variables. You can also pass these environment variables when you are [building your Storybook](../sharing/publish-storybook.md) with `build-storybook`. @@ -115,12 +79,7 @@ Additionally, you can extend your Storybook configuration file (i.e., [`.storybo {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -128,17 +87,7 @@ When Storybook loads, it will enable you to access them in your stories similar {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -155,9 +104,7 @@ The table below lists the available options: | Chromium | `BROWSER="chromium"` | - -By default, Storybook will open a new Chrome window as part of its startup process. If you don't have Chrome installed, make sure to include one of the following options, or set your default browser accordingly. - + By default, Storybook will open a new Chrome window as part of its startup process. If you don't have Chrome installed, make sure to include one of the following options, or set your default browser accordingly. ## Troubleshooting diff --git a/docs/configure/features-and-behavior.mdx b/docs/configure/features-and-behavior.mdx index 87432569ccde..6e173154d57e 100644 --- a/docs/configure/features-and-behavior.mdx +++ b/docs/configure/features-and-behavior.mdx @@ -6,11 +6,7 @@ To control the layout of Storybook’s UI you can use `addons.setConfig` in your {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/configure/frameworks-feature-support.mdx b/docs/configure/frameworks-feature-support.mdx index 79013ad8fc4b..ace6bb8d97b7 100644 --- a/docs/configure/frameworks-feature-support.mdx +++ b/docs/configure/frameworks-feature-support.mdx @@ -114,4 +114,4 @@ To align the Storybook ecosystem with the current state of frontend development, | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Knobs](https://github.com/storybookjs/addon-knobs) | The Knobs addon was officially deprecated with the release of Storybook 6.3 and is no longer actively maintained. We recommend using the [controls](../essentials/controls.md) instead. | | [Storyshots](../writing-tests/snapshot-testing.md) | The Storyshots addon was officially deprecated with the release of Storybook 7.6, is no longer actively maintained and was removed in Storybook 8. See the [migration guide](../writing-tests/storyshots-migration-guide.md) for the available alternatives. | -| StoriesOf | The `storiesOf` API was officially removed with the release of Storybook 8 and is no longer maintained. We recommend using the [CSF API](../api/csf.md) instead for writing stories.
See the [migration guide](../migration-guide.md#storiesof-to-csf) for more information. | +| StoriesOf | The `storiesOf` API was officially removed with the release of Storybook 8 and is no longer maintained. We recommend using the [CSF API](../api/csf.md) instead for writing stories.
See the [migration guide](../migration-guide.md#storiesof-to-csf) for more information. | diff --git a/docs/configure/frameworks.mdx b/docs/configure/frameworks.mdx index dcfafaca1d9d..e155888c9507 100644 --- a/docs/configure/frameworks.mdx +++ b/docs/configure/frameworks.mdx @@ -27,25 +27,20 @@ Every modern web application has unique requirements and relies on various tools {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} | Option | Description | Framework | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -| `nextConfigPath` | Sets the default path for the NextJS configuration file
`framework: { name: '@storybook/nextjs', options: { nextConfigPath: '../next.config.js'} }` | NextJS | -| `builder` | Configures [Webpack 5](../builders/webpack.md) builder options for NextJS
`core: { builder: { name:'webpack5', options: { lazyCompilation: true} }}` | NextJS | -| `strictMode` | Enables React's [strict mode](https://reactjs.org/docs/strict-mode.html)
`framework: { name: '@storybook/react-webpack5', options: { strictMode: false } }` | React | -| `legacyRootApi` | Requires React 18. Toggles support for React's [legacy root API](https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#updates-to-client-rendering-apis)
`framework: { name: '@storybook/react-webpack5', options: { legacyRootApi: true } }` | React | -| `enableIvy` | Enabled by default with Angular 9+. Replaces the default compiler with the [Ivy compiler](https://docs.angular.lat/guide/ivy)
`framework: { name: '@storybook/angular', options: { enableIvy: true } }` | Angular | -| `enableNgcc` | Enabled by default with Angular 9+. Adds support for ngcc for backwards compatibility
`framework: { name: '@storybook/angular', options: { enableNgcc: false } }` | Angular | +| `nextConfigPath` | Sets the default path for the NextJS configuration file
`framework: { name: '@storybook/nextjs', options: { nextConfigPath: '../next.config.js'} }` | NextJS | +| `builder` | Configures [Webpack 5](../builders/webpack.md) builder options for NextJS
`core: { builder: { name:'webpack5', options: { lazyCompilation: true} }}` | NextJS | +| `strictMode` | Enables React's [strict mode](https://reactjs.org/docs/strict-mode.html)
`framework: { name: '@storybook/react-webpack5', options: { strictMode: false } }` | React | +| `legacyRootApi` | Requires React 18. Toggles support for React's [legacy root API](https://reactjs.org/blog/2022/03/08/react-18-upgrade-guide.html#updates-to-client-rendering-apis)
`framework: { name: '@storybook/react-webpack5', options: { legacyRootApi: true } }` | React | +| `enableIvy` | Enabled by default with Angular 9+. Replaces the default compiler with the [Ivy compiler](https://docs.angular.lat/guide/ivy)
`framework: { name: '@storybook/angular', options: { enableIvy: true } }` | Angular | +| `enableNgcc` | Enabled by default with Angular 9+. Adds support for ngcc for backwards compatibility
`framework: { name: '@storybook/angular', options: { enableNgcc: false } }` | Angular | ---- +*** ## Troubleshooting @@ -67,7 +62,7 @@ We're deprecating support for several frameworks, including [Aurelia](https://gi ### Learn about configuring Storybook -- [Theming](./theming.md) to customize the look and feel of Storybook's UI -- [CSS](./styling-and-css.md) to configure CSS support -- [Images & assets](./images-and-assets.md) for static asset handling -- [Environment variables](./environment-variables.md) to configure environment variables +* [Theming](./theming.md) to customize the look and feel of Storybook's UI +* [CSS](./styling-and-css.md) to configure CSS support +* [Images & assets](./images-and-assets.md) for static asset handling +* [Environment variables](./environment-variables.md) to configure environment variables diff --git a/docs/configure/images-and-assets.mdx b/docs/configure/images-and-assets.mdx index 6dbd9513905c..f1cde19d5cc5 100644 --- a/docs/configure/images-and-assets.mdx +++ b/docs/configure/images-and-assets.mdx @@ -12,23 +12,7 @@ Afterward, you can use any asset in your stories: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -40,12 +24,7 @@ Configure a directory (or a list of directories) where your assets live when sta {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -53,23 +32,7 @@ Here `../public` is your static directory. Now use it in a component or story li {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -77,12 +40,7 @@ You can also pass a list of directories separated by commas without spaces inste {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -90,12 +48,7 @@ Or even use a configuration object to define the directories: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -105,23 +58,7 @@ Upload your files to an online CDN and reference them. In this example, we’re {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -141,7 +78,6 @@ After configuring Storybook to serve assets from your static folder, you can ref {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/configure/index.mdx b/docs/configure/index.mdx index 1cb28c886b86..54785bddc01d 100644 --- a/docs/configure/index.mdx +++ b/docs/configure/index.mdx @@ -5,9 +5,7 @@ title: 'Configure Storybook' Storybook is configured via a folder called `.storybook`, which contains various configuration files. - -Note that you can change the folder that Storybook uses by setting the `-c` flag to your `storybook dev` and `storybook build` [CLI commands](../api/cli-options.md). - + Note that you can change the folder that Storybook uses by setting the `-c` flag to your `storybook dev` and `storybook build` [CLI commands](../api/cli-options.md). ## Configure your Storybook project @@ -16,37 +14,30 @@ Storybook's main configuration (i.e., the `main.js|ts`) defines your Storybook p {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -This configuration file is a [preset](../addons/addon-types.md) and, as such, has a powerful interface, which can be further customized. Read our documentation on writing [presets](../addons/writing-presets.md) to learn more. - + This configuration file is a [preset](../addons/addon-types.md) and, as such, has a powerful interface, which can be further customized. Read our documentation on writing [presets](../addons/writing-presets.md) to learn more. | Configuration element | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `stories` | The array of globs that indicates the [location of your story files](#configure-story-loading), relative to `main.js` | -| `staticDirs` | Sets a list of directories of [static files](./images-and-assets.md#serving-static-files-via-storybook-configuration) to be loaded by Storybook
`staticDirs: ['../public']` | -| `addons` | Sets the list of [addons](https://storybook.js.org/integrations) loaded by Storybook
`addons: ['@storybook/addon-essentials']` | -| `typescript` | Configures how Storybook handles [TypeScript files](./typescript.md)
`typescript: { check: false, checkOptions: {} }` | -| `framework` | Configures Storybook based on a set of [framework-specific](./frameworks.md) settings
`framework: { name: '@storybook/svelte-vite', options:{} }` | -| `core` | Configures Storybook's [internal features](../api/main-config-core.md)
`core: { disableTelemetry: true, }` | -| `docs` | Configures Storybook's [auto-generated documentation](../writing-docs/autodocs.md)
`docs: { autodocs: 'tag' }` | -| `features` | Enables Storybook's [additional features](../api/main-config-features.md)
See table below for a list of available features | -| `refs` | Configures [Storybook composition](../sharing/storybook-composition.md)
`refs:{ example: { title: 'ExampleStorybook', url:'https://your-url.com' } }` | -| `logLevel` | Configures Storybook's logs in the browser terminal. Useful for debugging
`logLevel: 'debug'` | -| `webpackFinal` | Customize Storybook's [Webpack](../builders/webpack.md) setup
`webpackFinal: async (config:any) => { return config; }` | -| `viteFinal` | Customize Storybook's Vite setup when using the [vite builder](https://github.com/storybookjs/builder-vite)
`viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; }` | -| `env` | Defines custom Storybook [environment variables](./environment-variables.md#using-storybook-configuration).
`env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }),` | -| `build` | Optimizes Storybook's production [build](../api/main-config-build.md) for performance by excluding specific features from the bundle. Useful when decreased build times are a priority.
`build: { test: {} }` | +| `staticDirs` | Sets a list of directories of [static files](./images-and-assets.md#serving-static-files-via-storybook-configuration) to be loaded by Storybook
`staticDirs: ['../public']` | +| `addons` | Sets the list of [addons](https://storybook.js.org/integrations) loaded by Storybook
`addons: ['@storybook/addon-essentials']` | +| `typescript` | Configures how Storybook handles [TypeScript files](./typescript.md)
`typescript: { check: false, checkOptions: {} }` | +| `framework` | Configures Storybook based on a set of [framework-specific](./frameworks.md) settings
`framework: { name: '@storybook/svelte-vite', options:{} }` | +| `core` | Configures Storybook's [internal features](../api/main-config-core.md)
`core: { disableTelemetry: true, }` | +| `docs` | Configures Storybook's [auto-generated documentation](../writing-docs/autodocs.md)
`docs: { autodocs: 'tag' }` | +| `features` | Enables Storybook's [additional features](../api/main-config-features.md)
See table below for a list of available features | +| `refs` | Configures [Storybook composition](../sharing/storybook-composition.md)
`refs:{ example: { title: 'ExampleStorybook', url:'https://your-url.com' } }` | +| `logLevel` | Configures Storybook's logs in the browser terminal. Useful for debugging
`logLevel: 'debug'` | +| `webpackFinal` | Customize Storybook's [Webpack](../builders/webpack.md) setup
`webpackFinal: async (config:any) => { return config; }` | +| `viteFinal` | Customize Storybook's Vite setup when using the [vite builder](https://github.com/storybookjs/builder-vite)
`viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; }` | +| `env` | Defines custom Storybook [environment variables](./environment-variables.md#using-storybook-configuration).
`env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }),` | +| `build` | Optimizes Storybook's production [build](../api/main-config-build.md) for performance by excluding specific features from the bundle. Useful when decreased build times are a priority.
`build: { test: {} }` | ## Configure story loading @@ -65,12 +56,7 @@ For example, if you wanted to pull both `.md` and `.js` files from the `my-proje {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -80,12 +66,7 @@ Additionally, you can customize your Storybook configuration to load your storie {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -97,12 +78,7 @@ You can also simplify your Storybook configuration and load the stories using a {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -112,12 +88,7 @@ You can also adjust your Storybook configuration and implement custom logic to l {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -125,8 +96,8 @@ You can also adjust your Storybook configuration and implement custom logic to l Because of the way stories are currently indexed in Storybook, loading stories on demand has a couple of minor limitations at the moment: -- [CSF formats](../api/csf.md) from version 1 to version 3 are supported. -- Custom `storySort` functions are allowed based on a restricted API. +* [CSF formats](../api/csf.md) from version 1 to version 3 are supported. +* Custom `storySort` functions are allowed based on a restricted API. ## Configure story rendering @@ -134,9 +105,9 @@ To control the way stories are rendered and add global [decorators](../writing-s The `preview.js` file can be an ES module and export the following keys: -- `decorators` - an array of global [decorators](../writing-stories/decorators.md#global-decorators) -- `parameters` - an object of global [parameters](../writing-stories/parameters.md#global-parameters) -- `globalTypes` - definition of [globalTypes](../essentials/toolbars-and-globals.md#global-types-and-the-toolbar-annotation) +* `decorators` - an array of global [decorators](../writing-stories/decorators.md#global-decorators) +* `parameters` - an object of global [parameters](../writing-stories/parameters.md#global-parameters) +* `globalTypes` - definition of [globalTypes](../essentials/toolbars-and-globals.md#global-types-and-the-toolbar-annotation) If you’re looking to change how to order your stories, read about [sorting stories](../writing-stories/naming-components-and-hierarchy.md#sorting-stories). diff --git a/docs/configure/sidebar-and-urls.mdx b/docs/configure/sidebar-and-urls.mdx index 66f37b6480c2..37b8cf05a9e0 100644 --- a/docs/configure/sidebar-and-urls.mdx +++ b/docs/configure/sidebar-and-urls.mdx @@ -20,11 +20,7 @@ If you’d prefer to show top-level nodes as folders rather than roots, you can {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -36,17 +32,7 @@ Consider the following story: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -56,17 +42,7 @@ It is possible to manually set the story's id, which is helpful if you want to r {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -78,17 +54,7 @@ Storybook 6.4 introduced [CSF 3.0](https://storybook.js.org/blog/component-story {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -98,12 +64,7 @@ Auto-titles work with explicit titling options like the component's `title` and {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -116,11 +77,7 @@ If you need, you can revert to the previous pattern by adding the following conf {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -132,14 +89,7 @@ If you need to preserve the naming scheme, you can add the `title` element to th {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -149,12 +99,7 @@ Additionally, if you customize your Storybook to load your stories based on a [c {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/configure/story-layout.mdx b/docs/configure/story-layout.mdx index faacf7a9d5a9..995e07546b41 100644 --- a/docs/configure/story-layout.mdx +++ b/docs/configure/story-layout.mdx @@ -10,12 +10,7 @@ You can add the parameter to your [`./storybook/preview.js`](./index.md#configur {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -23,9 +18,9 @@ You can add the parameter to your [`./storybook/preview.js`](./index.md#configur In the example above, Storybook will center all stories in the UI. `layout` accepts these options: -- `centered`: center the component horizontally and vertically in the Canvas -- `fullscreen`: allow the component to expand to the full width and height of the Canvas -- `padded`: _(default)_ Add extra padding around the component +* `centered`: center the component horizontally and vertically in the Canvas +* `fullscreen`: allow the component to expand to the full width and height of the Canvas +* `padded`: *(default)* Add extra padding around the component ## Component layout @@ -33,15 +28,7 @@ You can also set it at a component level like so: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -51,16 +38,6 @@ Or even apply it to specific stories like so: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/configure/story-rendering.mdx b/docs/configure/story-rendering.mdx index aae973b80c39..0dbe7a5a78c9 100644 --- a/docs/configure/story-rendering.mdx +++ b/docs/configure/story-rendering.mdx @@ -9,71 +9,52 @@ In Storybook, your stories render in a particular “preview” iframe (also cal Code executed in the preview file (`.storybook/preview.js|ts`) runs for every story in your Storybook. This is useful for setting up global styles, initializing libraries, or anything else required to render your components. + Here's an example of how you might use the preview file to initialize a library that must run before your components render: -Here's an example of how you might use the preview file to initialize a library that must run before your components render: + ```ts + // .storybook/preview.ts + // Replace your-renderer with the renderer you are using (e.g., react, vue3) + import { Preview } from '@storybook/your-renderer'; -```ts -// .storybook/preview.ts -// Replace your-renderer with the renderer you are using (e.g., react, vue3) -import { Preview } from '@storybook/your-renderer'; + import { initialize } from '../lib/your-library'; -import { initialize } from '../lib/your-library'; + initialize(); -initialize(); - -const preview: Preview = { - // ... -}; - -export default preview; -``` + const preview: Preview = { + // ... + }; + export default preview; + ``` + For example, with Vue, you can extend Storybook's application and register your library (e.g., [Fontawesome](https://github.com/FortAwesome/vue-fontawesome)). Or with Angular, add the package ([localize](https://angular.io/api/localize)) into your `polyfills.ts` and import it: -For example, with Vue, you can extend Storybook's application and register your library (e.g., [Fontawesome](https://github.com/FortAwesome/vue-fontawesome)). Or with Angular, add the package ([localize](https://angular.io/api/localize)) into your `polyfills.ts` and import it: - -{/* prettier-ignore-start */} - - + {/* prettier-ignore-start */} -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} -## Adding to <head> +## Adding to \ If you need to add extra elements to the `head` of the preview iframe, for instance, to load static stylesheets, font files, or similar, you can create a file called [`.storybook/preview-head.html`](./index.md#configure-story-rendering) and add tags like this: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -Storybook will inject these tags into the _preview iframe_ where your components render, not the Storybook application UI. - + Storybook will inject these tags into the *preview iframe* where your components render, not the Storybook application UI. However, it's also possible to modify the preview head HTML programmatically using a preset defined in the `main.js` file. Read the [presets documentation](../addons/writing-presets.md#ui-configuration) for more information. -## Adding to <body> +## Adding to \ Sometimes, you may need to add different tags to the ``. Helpful for adding some custom content roots. @@ -81,11 +62,7 @@ You can accomplish this by creating a file called `preview-body.html` inside you {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -93,18 +70,12 @@ If using relative sizing in your project (like `rem` or `em`), you may update th {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -Storybook will inject these tags into the _preview iframe_ where your components render, not the Storybook application UI. - + Storybook will inject these tags into the *preview iframe* where your components render, not the Storybook application UI. Just like how you have the ability to customize the preview `head` HTML tag, you can also follow the same steps to customize the preview `body` with a preset. To obtain more information on how to do this, refer to the [presets documentation](../addons/writing-presets.md#ui-configuration). diff --git a/docs/configure/storybook-addons.mdx b/docs/configure/storybook-addons.mdx index 697e0884889a..b75718ef7119 100644 --- a/docs/configure/storybook-addons.mdx +++ b/docs/configure/storybook-addons.mdx @@ -20,6 +20,6 @@ Finally, addons can affect the build setup of Storybook by injecting their own w There are many, many Storybook addons, but they can be roughly categorized into three areas: -- **Essential** addons are core-team developed addons that are considered a part of the out-of-the-box user experience. These ship by default with new Storybook installations. -- **Core** addons are developed by the core team. They are kept in sync with the development of Storybook itself and written in idiomatic ways as templates for other addons. They can be found within the [Storybook monorepo](https://github.com/storybookjs/storybook/tree/next/code/addons). -- **Community** addons are addons written by the massive Storybook community. They can be found on our [website](https://storybook.js.org/addons/), [GitHub](https://github.com/), and [npm](https://www.npmjs.com/). +* **Essential** addons are core-team developed addons that are considered a part of the out-of-the-box user experience. These ship by default with new Storybook installations. +* **Core** addons are developed by the core team. They are kept in sync with the development of Storybook itself and written in idiomatic ways as templates for other addons. They can be found within the [Storybook monorepo](https://github.com/storybookjs/storybook/tree/next/code/addons). +* **Community** addons are addons written by the massive Storybook community. They can be found on our [website](https://storybook.js.org/addons/), [GitHub](https://github.com/), and [npm](https://www.npmjs.com/). diff --git a/docs/configure/styling-and-css.mdx b/docs/configure/styling-and-css.mdx index d9a544432c61..7575a94227e1 100644 --- a/docs/configure/styling-and-css.mdx +++ b/docs/configure/styling-and-css.mdx @@ -3,233 +3,204 @@ title: 'Styling and CSS' --- {/* Not Angular */} + + There are many ways to include CSS in a web application, and correspondingly there are many ways to include CSS in Storybook. Usually, it is best to try and replicate what your application does with styling in Storybook’s configuration. -There are many ways to include CSS in a web application, and correspondingly there are many ways to include CSS in Storybook. Usually, it is best to try and replicate what your application does with styling in Storybook’s configuration. + ## CSS -## CSS + Storybook supports importing CSS files in a few different ways. Storybook will inject these tags into the preview iframe where your components render, not the Storybook Manager UI. The best way to import CSS depends on your project's configuration and your preferences. -Storybook supports importing CSS files in a few different ways. Storybook will inject these tags into the preview iframe where your components render, not the Storybook Manager UI. The best way to import CSS depends on your project's configuration and your preferences. + ### Import bundled CSS (Recommended) -### Import bundled CSS (Recommended) + All Storybooks are pre-configured to recognize imports for CSS files. To add global CSS for all your stories, import it in [`.storybook/preview.ts`](./overview.md#configure-story-rendering). These files will be subject to HMR, so you can see your changes without restarting your Storybook server. -All Storybooks are pre-configured to recognize imports for CSS files. To add global CSS for all your stories, import it in [`.storybook/preview.ts`](./overview.md#configure-story-rendering). These files will be subject to HMR, so you can see your changes without restarting your Storybook server. + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} + - + {/* prettier-ignore-end */} -{/* prettier-ignore-end */} + If your component files import their CSS files, this will work too. However, if you're using CSS processor tools like Sass or Postcss, you may need some more configuration. -If your component files import their CSS files, this will work too. However, if you're using CSS processor tools like Sass or Postcss, you may need some more configuration. + ### Include static CSS -### Include static CSS + If you have a global CSS file that you want to include in all your stories, you can import it in [`.storybook/preview-head.html`](./story-rendering.md#adding-to-head). + However, these files will not be subject to HMR, so you'll need to restart your Storybook server to see your changes. -If you have a global CSS file that you want to include in all your stories, you can import it in [`.storybook/preview-head.html`](./story-rendering.md#adding-to-head). -However, these files will not be subject to HMR, so you'll need to restart your Storybook server to see your changes. + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} + - + {/* prettier-ignore-end */} -{/* prettier-ignore-end */} + ## CSS modules -## CSS modules + ### Vite -### Vite + Vite comes with CSS modules support out-of-the-box. If you have customized the CSS modules configuration in your `vite.config.js` this will automatically be applied to your Storybook as well. Read more about [Vite's CSS modules support](https://vitejs.dev/guide/features.html#css-modules). -Vite comes with CSS modules support out-of-the-box. If you have customized the CSS modules configuration in your `vite.config.js` this will automatically be applied to your Storybook as well. Read more about [Vite's CSS modules support](https://vitejs.dev/guide/features.html#css-modules). + ### Webpack -### Webpack + + + Storybook recreates your Next.js configuration, so you can use CSS modules in your stories without any extra configuration. + + - - + If you're using Webpack and want to use CSS modules, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling-webpack`](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) to help you configure these tools. -Storybook recreates your Next.js configuration, so you can use CSS modules in your stories without any extra configuration. + ## PostCSS - - + ### Vite -If you're using Webpack and want to use CSS modules, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling-webpack`](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) to help you configure these tools. + Vite comes with PostCSS support out-of-the-box. If you have customized the PostCSS configuration in your `vite.config.js` this will automatically be applied to your Storybook as well. Read more about [Vite's PostCSS support](https://vitejs.dev/guide/features.html#postcss). -## PostCSS + ### Webpack -### Vite + + + Storybook recreates your Next.js configuration, so you can use PostCSS in your stories without any extra configuration. + + -Vite comes with PostCSS support out-of-the-box. If you have customized the PostCSS configuration in your `vite.config.js` this will automatically be applied to your Storybook as well. Read more about [Vite's PostCSS support](https://vitejs.dev/guide/features.html#postcss). + If you're using Webpack and want to use PostCSS, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling-webpack`](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) to help you configure these tools. -### Webpack + ## CSS pre-processors - - + ### Vite -Storybook recreates your Next.js configuration, so you can use PostCSS in your stories without any extra configuration. + Vite comes with Sass, Less, and Stylus support out-of-the-box. Read more about [Vite's CSS Pre-processor support](https://vitejs.dev/guide/features.html#css-pre-processors). - - + ### Webpack -If you're using Webpack and want to use PostCSS, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling-webpack`](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) to help you configure these tools. + + + Storybook recreates your Next.js configuration, so you can use Sass in your stories without any extra configuration. + + -## CSS pre-processors + If you're using Webpack and want to use Sass or less, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling-webpack`](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) to help you configure these tools. Or if you'd prefer, you can customize [Storybook's webpack configuration yourself](../builders/webpack.md#override-the-default-configuration) to include the appropriate loader(s). -### Vite + ## CSS-in-JS -Vite comes with Sass, Less, and Stylus support out-of-the-box. Read more about [Vite's CSS Pre-processor support](https://vitejs.dev/guide/features.html#css-pre-processors). + CSS-in-JS libraries are designed to use basic JavaScript, and they often work in Storybook without any extra configuration. Some libraries expect components to render in a specific rendering “context” (for example, to provide themes), which can be accomplished with `@storybook/addon-themes`'s [`withThemeFromJSXProvider` decorator](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider). -### Webpack + ## Adding webfonts - - + ### `.storybook/preview-head.html` -Storybook recreates your Next.js configuration, so you can use Sass in your stories without any extra configuration. - - - + If you need webfonts to be available, you may need to add some code to the [`.storybook/preview-head.html`](./story-rendering.md#adding-to-head) file. We recommend including any assets with your Storybook if possible, in which case you likely want to configure the [static file location](./images-and-assets.md#serving-static-files-via-storybook-configuration). -If you're using Webpack and want to use Sass or less, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling-webpack`](https://storybook.js.org/addons/@storybook/addon-styling-webpack/) to help you configure these tools. Or if you'd prefer, you can customize [Storybook's webpack configuration yourself](../builders/webpack.md#override-the-default-configuration) to include the appropriate loader(s). + ### `.storybook/preview.ts` -## CSS-in-JS - -CSS-in-JS libraries are designed to use basic JavaScript, and they often work in Storybook without any extra configuration. Some libraries expect components to render in a specific rendering “context” (for example, to provide themes), which can be accomplished with `@storybook/addon-themes`'s [`withThemeFromJSXProvider` decorator](https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#withthemefromjsxprovider). - -## Adding webfonts - -### `.storybook/preview-head.html` + If you're using something like [`fontsource`](https://fontsource.org/) for your fonts, you can import the needed css files in your [`.storybook/preview.ts`](./overview.md#configure-story-rendering) file. + -If you need webfonts to be available, you may need to add some code to the [`.storybook/preview-head.html`](./story-rendering.md#adding-to-head) file. We recommend including any assets with your Storybook if possible, in which case you likely want to configure the [static file location](./images-and-assets.md#serving-static-files-via-storybook-configuration). +{/* Angular only */} -### `.storybook/preview.ts` + + Storybook for Angular relies on the Angular CLI to build your stories. This means that you can use any CSS preprocessor that the Angular CLI supports. You can read more about this in the [Angular CLI documentation](https://angular.io/guide/workspace-config#style-script-config). -If you're using something like [`fontsource`](https://fontsource.org/) for your fonts, you can import the needed css files in your [`.storybook/preview.ts`](./overview.md#configure-story-rendering) file. + ## Global styles - + To add global styles to your Storybook, you can add them to the `styles` array in your `angular.json` file. This will add the styles to the preview iframe where your components render, not the Storybook Manager UI. -{/* Angular only */} - + Don't forget to also add your global styles to your `build-storybook` target in your `angular.json` file. This will ensure that your global styles are included in the static build of your Storybook as well. -Storybook for Angular relies on the Angular CLI to build your stories. This means that you can use any CSS preprocessor that the Angular CLI supports. You can read more about this in the [Angular CLI documentation](https://angular.io/guide/workspace-config#style-script-config). - -## Global styles - -To add global styles to your Storybook, you can add them to the `styles` array in your `angular.json` file. This will add the styles to the preview iframe where your components render, not the Storybook Manager UI. - -Don't forget to also add your global styles to your `build-storybook` target in your `angular.json` file. This will ensure that your global styles are included in the static build of your Storybook as well. - -```json -{ - "storybook": { - "builder": "@storybook/angular:start-storybook", - "options": { - "configDir": ".storybook", - "browserTarget": "angular-latest:build", - "compodoc": true, - "compodocArgs": ["-e", "json", "-d", "."], - "port": 6006, - "styles": [ - // Add your global styles here - "@angular/material/prebuilt-themes/indigo-pink.css", - "@fontsource/roboto/300.css", - "@fontsource/roboto/400.css", - "@fontsource/roboto/500.css", - "@fontsource/roboto/700.css", - "@fontsource/material-icons", - "src/styles.scss" - ] - } - }, - "build-storybook": { - "builder": "@storybook/angular:build-storybook", - "options": { - "configDir": ".storybook", - "browserTarget": "angular-latest:build", - "compodoc": true, - "compodocArgs": ["-e", "json", "-d", "."], - "styles": [ - // Add your global styles here - "@angular/material/prebuilt-themes/indigo-pink.css", - "@fontsource/roboto/300.css", - "@fontsource/roboto/400.css", - "@fontsource/roboto/500.css", - "@fontsource/roboto/700.css", - "@fontsource/material-icons", - "src/styles.scss" - ], - "outputDir": "storybook-static" + ```json + { + "storybook": { + "builder": "@storybook/angular:start-storybook", + "options": { + "configDir": ".storybook", + "browserTarget": "angular-latest:build", + "compodoc": true, + "compodocArgs": ["-e", "json", "-d", "."], + "port": 6006, + "styles": [ + // Add your global styles here + "@angular/material/prebuilt-themes/indigo-pink.css", + "@fontsource/roboto/300.css", + "@fontsource/roboto/400.css", + "@fontsource/roboto/500.css", + "@fontsource/roboto/700.css", + "@fontsource/material-icons", + "src/styles.scss" + ] + } + }, + "build-storybook": { + "builder": "@storybook/angular:build-storybook", + "options": { + "configDir": ".storybook", + "browserTarget": "angular-latest:build", + "compodoc": true, + "compodocArgs": ["-e", "json", "-d", "."], + "styles": [ + // Add your global styles here + "@angular/material/prebuilt-themes/indigo-pink.css", + "@fontsource/roboto/300.css", + "@fontsource/roboto/400.css", + "@fontsource/roboto/500.css", + "@fontsource/roboto/700.css", + "@fontsource/material-icons", + "src/styles.scss" + ], + "outputDir": "storybook-static" + } } } -} -``` + ``` -## Troubleshooting + ## Troubleshooting -If you're working with Storybook and [Nx libraries](https://nx.dev/structure/library-types), you can extend your project's configuration (i.e., project.json) and provide the application's styles. + If you're working with Storybook and [Nx libraries](https://nx.dev/structure/library-types), you can extend your project's configuration (i.e., project.json) and provide the application's styles. -For earlier Nx versions (before 14.1.8), your configuration would look like this: + For earlier Nx versions (before 14.1.8), your configuration would look like this: -```json - "build-storybook": { - "executor": "@nrwl/storybook:build", - "outputs": ["{options.outputPath}"], - "options": { - "uiFramework": "@storybook/angular", - "outputPath": "dist/storybook/example-lib", - "config": { - "configFolder": "libs/example-lib/storybook/.storybook" - }, - "projectBuildConfig": "example-lib:build-storybook", - "styles": ["apps/example-app/src/styles.scss"] + ```json + "build-storybook": { + "executor": "@nrwl/storybook:build", + "outputs": ["{options.outputPath}"], + "options": { + "uiFramework": "@storybook/angular", + "outputPath": "dist/storybook/example-lib", + "config": { + "configFolder": "libs/example-lib/storybook/.storybook" + }, + "projectBuildConfig": "example-lib:build-storybook", + "styles": ["apps/example-app/src/styles.scss"] + } } - } -``` + ``` -Starting with version 14.1.8, Nx uses the Storybook builder directly, which means any configuration supplied to the builder also applies to the NX setup. If you're working with a library, you'll need to configure the styling options ( e.g., preprocessors) inside the `build-storybook` options configuration object. For example: + Starting with version 14.1.8, Nx uses the Storybook builder directly, which means any configuration supplied to the builder also applies to the NX setup. If you're working with a library, you'll need to configure the styling options ( e.g., preprocessors) inside the `build-storybook` options configuration object. For example: -```json - "storybook": { - "executor": "@storybook/angular:start-storybook", - "options": { - "configDir": "apps/example-lib/.storybook", - "browserTarget": "example-lib:build-storybook", + ```json + "storybook": { + "executor": "@storybook/angular:start-storybook", + "options": { + "configDir": "apps/example-lib/.storybook", + "browserTarget": "example-lib:build-storybook", + }, }, - }, - "build-storybook": { - "executor": "@storybook/angular:build-storybook", - "outputs": ["{options.outputPath}"], - "options": { - "outputDir": "dist/storybook/example-lib", - "configDir": "apps/example-lib/.storybook", - "browserTarget": "example-lib:build-storybook", - "styles": [".storybook/custom-styles.scss"], - "stylePreprocessorOptions": { - "includePaths": [ - "libs/design-system/src/lib" - ] + "build-storybook": { + "executor": "@storybook/angular:build-storybook", + "outputs": ["{options.outputPath}"], + "options": { + "outputDir": "dist/storybook/example-lib", + "configDir": "apps/example-lib/.storybook", + "browserTarget": "example-lib:build-storybook", + "styles": [".storybook/custom-styles.scss"], + "stylePreprocessorOptions": { + "includePaths": [ + "libs/design-system/src/lib" + ] + } } } - } -``` - -When Nx runs, it will load Storybook's configuration and styling based on [`storybook.browserTarget`](https://nx.dev/storybook/extra-topics-for-angular-projects#setting-up-browsertarget). + ``` + When Nx runs, it will load Storybook's configuration and styling based on [`storybook.browserTarget`](https://nx.dev/storybook/extra-topics-for-angular-projects#setting-up-browsertarget). diff --git a/docs/configure/telemetry.mdx b/docs/configure/telemetry.mdx index c84a3cb46bef..13afcfc4746b 100644 --- a/docs/configure/telemetry.mdx +++ b/docs/configure/telemetry.mdx @@ -8,10 +8,10 @@ Storybook collects completely anonymous data to help us improve user experience. Hundreds of thousands of developers use Storybook daily to build, test, and document components. Storybook is framework agnostic and integrates with the front-end ecosystem: -- **JavaScript frameworks** such as [React](https://reactjs.org/), [Vue 3](https://vuejs.org/), [Svelte](https://svelte.dev/) and [Solid](https://www.solidjs.com/) -- **Libraries** such as [Styled-Components](https://styled-components.com/), [Tailwind](https://tailwindcss.com/), [Redux](https://redux.js.org/) -- **Design tools** such as [Figma](https://figma.com/), [Sketch](https://www.sketch.com/), [Zeplin](https://zeplin.io/) and [InVision](https://www.invisionapp.com/) -- **Workflow tools** such as [Notion](https://www.notion.so/product), [Confluence](https://www.atlassian.com/software/confluence), and [Jira](https://www.atlassian.com/software/jira) +* **JavaScript frameworks** such as [React](https://reactjs.org/), [Vue 3](https://vuejs.org/), [Svelte](https://svelte.dev/) and [Solid](https://www.solidjs.com/) +* **Libraries** such as [Styled-Components](https://styled-components.com/), [Tailwind](https://tailwindcss.com/), [Redux](https://redux.js.org/) +* **Design tools** such as [Figma](https://figma.com/), [Sketch](https://www.sketch.com/), [Zeplin](https://zeplin.io/) and [InVision](https://www.invisionapp.com/) +* **Workflow tools** such as [Notion](https://www.notion.so/product), [Confluence](https://www.atlassian.com/software/confluence), and [Jira](https://www.atlassian.com/software/jira) In the past, our improvement process relied on manually gathering feedback. But with a growing userbase and the need to support a wide variety of integrations, we need a more accurate method for gauging Storybook usage and pain points. @@ -23,22 +23,22 @@ We collect general usage details, including command invocation, Storybook versio Specifically, we track the following information in our telemetry events: -- Timestamp of the occurrence. -- Command invoked (e.g., `init`, `upgrade`, `dev`, `build`). -- Storybook unique identifier: One-way hash generated during Storybook installation process. -- One way hash of the IP address where the event occurred for spam detection. -- Story count. -- Storybook version. -- Storybook metadata: - - Language (e.g., TypeScript, JavaScript). - - Supported view layers (e.g., React, Vue 3, Angular, Svelte). - - Builder (e.g., Webpack5, Vite). - - Meta framework (e.g., [Next](https://nextjs.org/), [Gatsby](https://www.gatsbyjs.com/), [CRA](https://create-react-app.dev/)). - - [Addons](https://storybook.js.org/integrations) (e.g., [Essentials](../essentials/index.md), [Accessibility](https://storybook.js.org/addons/@storybook/addon-a11y/)). - - Testing tools (e.g. [Jest](https://jestjs.io/), [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/)). -- Package manager information (e.g., `npm`, `yarn`). -- Monorepo information (e.g., [NX](https://nx.dev/), [Turborepo](https://turborepo.org/)). -- In-app events (e.g., [Storybook guided tour](https://github.com/storybookjs/addon-onboarding)). +* Timestamp of the occurrence. +* Command invoked (e.g., `init`, `upgrade`, `dev`, `build`). +* Storybook unique identifier: One-way hash generated during Storybook installation process. +* One way hash of the IP address where the event occurred for spam detection. +* Story count. +* Storybook version. +* Storybook metadata: + * Language (e.g., TypeScript, JavaScript). + * Supported view layers (e.g., React, Vue 3, Angular, Svelte). + * Builder (e.g., Webpack5, Vite). + * Meta framework (e.g., [Next](https://nextjs.org/), [Gatsby](https://www.gatsbyjs.com/), [CRA](https://create-react-app.dev/)). + * [Addons](https://storybook.js.org/integrations) (e.g., [Essentials](../essentials/index.md), [Accessibility](https://storybook.js.org/addons/@storybook/addon-a11y/)). + * Testing tools (e.g. [Jest](https://jestjs.io/), [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/)). +* Package manager information (e.g., `npm`, `yarn`). +* Monorepo information (e.g., [NX](https://nx.dev/), [Turborepo](https://turborepo.org/)). +* In-app events (e.g., [Storybook guided tour](https://github.com/storybookjs/addon-onboarding)). Access to the raw data is highly controlled, limited to select members of Storybook's core team who maintain the telemetry. We cannot identify individual users from the dataset: it is anonymized and untraceable back to the user. @@ -48,12 +48,7 @@ We take your privacy and our security very seriously. We perform additional step {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -161,23 +156,12 @@ You may opt-out of the telemetry by setting Storybook's configuration element `d {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -There is a `boot` event containing no metadata (used to ensure the telemetry is working). It is sent prior to evaluating your [Storybook configuration file](../api/main-config.md) (i.e., `main.js|ts`), so it is unaffected by the `disableTelemetry` option. If you want to ensure that the event is not sent, use the `STORYBOOK_DISABLE_TELEMETRY` environment variable. - + There is a `boot` event containing no metadata (used to ensure the telemetry is working). It is sent prior to evaluating your [Storybook configuration file](../api/main-config.md) (i.e., `main.js|ts`), so it is unaffected by the `disableTelemetry` option. If you want to ensure that the event is not sent, use the `STORYBOOK_DISABLE_TELEMETRY` environment variable. ## Crash reports (disabled by default) @@ -186,16 +170,7 @@ In addition to general usage telemetry, you may also choose to share crash repor {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -203,10 +178,6 @@ Generates the following item in the telemetry event: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/configure/theming.mdx b/docs/configure/theming.mdx index 4e45ef46e94c..ef84826c16d8 100644 --- a/docs/configure/theming.mdx +++ b/docs/configure/theming.mdx @@ -16,13 +16,7 @@ Make sure you have installed [`@storybook/manager-api`](https://www.npmjs.com/pa {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -30,11 +24,7 @@ As an example, you can tell Storybook to use the "dark" theme by modifying [`.st {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -48,11 +38,7 @@ Supposing you have a Storybook theme defined for the main UI in [`.storybook/man {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -60,12 +46,7 @@ Here's how you'd specify the same theme for docs in [`.storybook/preview.js`](./ {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -79,36 +60,26 @@ Inside your `.storybook` directory, create a new file called `YourTheme.js` and {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -If you're using `brandImage` to add your custom logo, you can use any of the most common image formats. - + If you're using `brandImage` to add your custom logo, you can use any of the most common image formats. Above, we're creating a new theme that will: -- Use Storybook's `light` theme as a baseline. -- Replace Storybook's logo in the sidebar with our own (defined in the brandImage variable). -- Add custom branding information. -- Set the brand link to open in the same window (as opposed to a new one), via the `target` attribute. +* Use Storybook's `light` theme as a baseline. +* Replace Storybook's logo in the sidebar with our own (defined in the brandImage variable). +* Add custom branding information. +* Set the brand link to open in the same window (as opposed to a new one), via the `target` attribute. Finally, we'll need to import the theme into Storybook. Create a new file called `manager.js` in your `.storybook` directory and add the following: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -120,27 +91,21 @@ Let's take a look at a more complex example. Copy the code below and paste it in {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} Above, we're updating the theme with the following changes: -- A custom color palette (defined in the `app` and `color` variables). -- Custom fonts (defined in the `font` and `text` variables). +* A custom color palette (defined in the `app` and `color` variables). +* Custom fonts (defined in the `font` and `text` variables). With the new changes introduced, the custom theme should yield a similar result. ![Storybook custom theme loaded](./storybook-custom-theme.png) - -Many theme variables are optional, the base property is **NOT**. - + Many theme variables are optional, the base property is **NOT**. The `@storybook/theming` package is built using TypeScript, which should help create a valid theme for TypeScript users. The types are part of the package itself. @@ -151,13 +116,11 @@ The Storybook theme API is narrow by design. If you want to have fine-grained co To style these elements, insert style tags into: -- For Storybook’s UI, use `.storybook/manager-head.html` -- For Storybook Docs, use `.storybook/preview-head.html` +* For Storybook’s UI, use `.storybook/manager-head.html` +* For Storybook Docs, use `.storybook/preview-head.html` - -The same way as you can adjust your [preview’s head tag](../configure/story-rendering.md#adding-to-head), Storybook allows you to modify the code on the manager's side, through `.storybook/manager-head.html`. It can be helpful when adding theme styles that target Storybook's HTML, but it comes with a cost as Storybook's inner HTML can change at any time through the release cycle. - + The same way as you can adjust your [preview’s head tag](../configure/story-rendering.md#adding-to-head), Storybook allows you to modify the code on the manager's side, through `.storybook/manager-head.html`. It can be helpful when adding theme styles that target Storybook's HTML, but it comes with a cost as Storybook's inner HTML can change at any time through the release cycle. ## MDX component overrides @@ -168,12 +131,7 @@ Here's how you might insert a custom code renderer for `code` blocks on the page {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -183,12 +141,7 @@ Here's how you might insert a custom `` block: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -200,11 +153,7 @@ For example, the popular Actions addon uses [react-inspector](https://github.com {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -214,11 +163,7 @@ Reuse the theme variables above for a native Storybook developer experience. The {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -226,11 +171,7 @@ Use the theme variables in object notation: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -238,10 +179,6 @@ Or with template literals: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/configure/typescript.mdx b/docs/configure/typescript.mdx index a1fbc49cd040..a53b539bd6b5 100644 --- a/docs/configure/typescript.mdx +++ b/docs/configure/typescript.mdx @@ -10,66 +10,48 @@ Storybook's configuration file (i.e., `main.ts`) is defined as an ESM module wri {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} See the [main configuration API reference](../api/main-config) for more details and additional properties. - -See the Vite builder [TypeScript documentation](https://github.com/storybookjs/builder-vite#typescript) if using `@storybook/builder-vite`. - + See the Vite builder [TypeScript documentation](https://github.com/storybookjs/builder-vite#typescript) if using `@storybook/builder-vite`. ### Extending the default configuration + Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props, inputs) from your components without any additional configuration. Since Storybook supports multiple frameworks, it also includes a set of third-party packages to support each framework (e.g., `ts-loader`, `vue-docgen-api` for Vue). If you need to customize the default configuration for a specific use case scenario, you can adjust your Storybook configuration file and provide the required options. Listed below are the available options and examples of how to use them. -Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props, inputs) from your components without any additional configuration. Since Storybook supports multiple frameworks, it also includes a set of third-party packages to support each framework (e.g., `ts-loader`, `vue-docgen-api` for Vue). If you need to customize the default configuration for a specific use case scenario, you can adjust your Storybook configuration file and provide the required options. Listed below are the available options and examples of how to use them. - -| Option | Description | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `check` | Available for Webpack-based projects.
Enables type checking within Storybook
`typescript: { check: true },` | -| `checkOptions` | Requires the `check` option to be enabled.
Configures the [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) plugin
`typescript: { checkOptions:{},},` | -| `skipCompiler` | Disables parsing Typescript files through the compiler
`typescript: { skipCompiler:false,},` | - + | Option | Description | + | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | `check` | Available for Webpack-based projects.
Enables type checking within Storybook
`typescript: { check: true },` | + | `checkOptions` | Requires the `check` option to be enabled.
Configures the [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) plugin
`typescript: { checkOptions:{},},` | + | `skipCompiler` | Disables parsing Typescript files through the compiler
`typescript: { skipCompiler:false,},` | - - -Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props) for your components without any additional configuration. It relies on [`react-docgen`](https://github.com/reactjs/react-docgen), a fast and highly customizable parser to process TypeScript files to infer the component's metadata and generate types automatically for improved performance and type safety. If you need to customize the default configuration for a specific use case scenario, you can adjust your Storybook configuration file and provide the required options. Listed below are the available options and examples of how to use them. - -| Option | Description | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `check` | Available for Webpack-based projects.
Enables type checking within Storybook
`typescript: { check: true },` | -| `checkOptions` | Requires the `check` option to be enabled.
Configures the [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) plugin
`typescript: { checkOptions: {},},` | -| `reactDocgen` | Configures the TypeScript parser used by Storybook.
Available options: `react-docgen` (default), `react-docgen-typescript`,` false`
`typescript: { reactDocgen: 'react-docgen'},` | -| `reactDocgenTypescriptOptions` | Requires the `reactDocgen`option to be `react-docgen-typescript`.
Configures the `react-docgen-typescript-plugin` plugin per builder
`typescript: { reactDocgen: 'react-docgen-typescript', reactDocgenTypescriptOptions: {},},` | -| `skipCompiler` | Disables parsing Typescript files through the compiler
`typescript: { skipCompiler:false,},` | + + Out of the box, Storybook is built to work with a wide range of third-party libraries, enabling you to safely access and document metadata (e.g., props) for your components without any additional configuration. It relies on [`react-docgen`](https://github.com/reactjs/react-docgen), a fast and highly customizable parser to process TypeScript files to infer the component's metadata and generate types automatically for improved performance and type safety. If you need to customize the default configuration for a specific use case scenario, you can adjust your Storybook configuration file and provide the required options. Listed below are the available options and examples of how to use them. + | Option | Description | + | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `check` | Available for Webpack-based projects.
Enables type checking within Storybook
`typescript: { check: true },` | + | `checkOptions` | Requires the `check` option to be enabled.
Configures the [`fork-ts-checker-webpack-plugin`](https://github.com/TypeStrong/fork-ts-checker-webpack-plugin) plugin
`typescript: { checkOptions: {},},` | + | `reactDocgen` | Configures the TypeScript parser used by Storybook.
Available options: `react-docgen` (default), `react-docgen-typescript`,` false`
`typescript: { reactDocgen: 'react-docgen'},` | + | `reactDocgenTypescriptOptions` | Requires the `reactDocgen`option to be `react-docgen-typescript`.
Configures the `react-docgen-typescript-plugin` plugin per builder
`typescript: { reactDocgen: 'react-docgen-typescript', reactDocgenTypescriptOptions: {},},` | + | `skipCompiler` | Disables parsing Typescript files through the compiler
`typescript: { skipCompiler:false,},` | {/* prettier-ignore-start */} - - + {/* prettier-ignore-end */} - -Additional options are available for the `typescript` configuration option. See the [`config.typescript` API reference](../api/main-config-typescript.md) for more information. - + Additional options are available for the `typescript` configuration option. See the [`config.typescript` API reference](../api/main-config-typescript.md) for more information. ## Write stories with TypeScript @@ -78,13 +60,7 @@ Storybook provides zero-config TypeScript support, allowing you to write stories {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -96,11 +72,7 @@ Assuming that you're working on a project that uses TypeScript 4.9+, you can upd {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -108,11 +80,7 @@ Now, when you define a story or update an existing one, you'll automatically get {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -123,44 +91,31 @@ Now, when you define a story or update an existing one, you'll automatically get Out of the box, Storybook supports the `satisfies` operator for almost every framework already using TypeScript version 4.9 or higher. However, due to the constraints of the Angular and Web Components framework, you might run into issues when applying this operator for additional type safety. This is primarily due to how both frameworks are currently implemented, making it almost impossible for Storybook to determine if the component property is required. If you encounter this issue, please open up a support request on [GitHub Discussions](https://github.com/storybookjs/storybook/discussions/new?category=help). + ### The TypeScript auto-completion is not working on my editor -### The TypeScript auto-completion is not working on my editor - -If you're using Vue single file components and TypeScript, you can add both [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) and the [TypeScript Vue Plugin](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) for editor support, additional type safety and auto-completion. Nevertheless, if you're working with Svelte, you can add the [Svelte for VSCode extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) for similar benefits. - + If you're using Vue single file components and TypeScript, you can add both [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) and the [TypeScript Vue Plugin](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) for editor support, additional type safety and auto-completion. Nevertheless, if you're working with Svelte, you can add the [Svelte for VSCode extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode) for similar benefits. - + + ### Storybook doesn't create the required types for external packages -### Storybook doesn't create the required types for external packages + If your project relies on a third-party library and the expected types are not being generated, preventing you from accurately documenting your components, you can adjust the `reactDocgen` configuration option in your Storybook configuration file to use `react-docgen-typescript` instead and include the required options. For example: -If your project relies on a third-party library and the expected types are not being generated, preventing you from accurately documenting your components, you can adjust the `reactDocgen` configuration option in your Storybook configuration file to use `react-docgen-typescript` instead and include the required options. For example: + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} + - + {/* prettier-ignore-end */} + ### The types are not being generated for my component -{/* prettier-ignore-end */} - -### The types are not being generated for my component + If you're working with a React project, type inference is automatically enabled for your components using the `react-docgen` library for improved build times and type safety. However, you may run into a situation where some options may not work as expected (e.g., [`Enums`](https://www.typescriptlang.org/docs/handbook/enums.html), React's [`forwardRef`](https://react.dev/reference/react/forwardRef)). This is primarily due to how the `react-docgen` package is implemented, making it difficult for Storybook to infer the component's metadata and generate types automatically. To solve this, you can update the `typescript` configuration option in your Storybook configuration file to use `react-docgen-typescript` instead. For example: -If you're working with a React project, type inference is automatically enabled for your components using the `react-docgen` library for improved build times and type safety. However, you may run into a situation where some options may not work as expected (e.g., [`Enums`](https://www.typescriptlang.org/docs/handbook/enums.html), React's [`forwardRef`](https://react.dev/reference/react/forwardRef)). This is primarily due to how the `react-docgen` package is implemented, making it difficult for Storybook to infer the component's metadata and generate types automatically. To solve this, you can update the `typescript` configuration option in your Storybook configuration file to use `react-docgen-typescript` instead. For example: + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} - - - -{/* prettier-ignore-end */} + -If you're still encountering issues, we recommend reaching out to the community using the default communication channels (e.g., [GitHub discussions](https://github.com/storybookjs/storybook/discussions/new?category=help)). + {/* prettier-ignore-end */} + If you're still encountering issues, we recommend reaching out to the community using the default communication channels (e.g., [GitHub discussions](https://github.com/storybookjs/storybook/discussions/new?category=help)). diff --git a/docs/configure/upgrading.mdx b/docs/configure/upgrading.mdx index 438e4801f765..762463886733 100644 --- a/docs/configure/upgrading.mdx +++ b/docs/configure/upgrading.mdx @@ -12,31 +12,23 @@ To help ease the pain of keeping Storybook up-to-date, we provide a command-line {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} The `upgrade` command will use whichever version you specify. For example: -- `storybook@latest upgrade` will upgrade to the latest version -- `storybook@7.6.10 upgrade` will upgrade to `7.6.10` -- `storybook@7 upgrade` will upgrade to the newest `7.x.x` version +* `storybook@latest upgrade` will upgrade to the latest version +* `storybook@7.6.10 upgrade` will upgrade to `7.6.10` +* `storybook@7 upgrade` will upgrade to the newest `7.x.x` version After running the command, the script will: -- Upgrade all Storybook packages in your project to the specified version -- Run the relevant [automigrations](../migration-guide.md#automatic-upgrade) factoring in the [breaking changes](../migration-guide.md#major-breaking-changes) between your current version and the specified version +* Upgrade all Storybook packages in your project to the specified version +* Run the relevant [automigrations](../migration-guide.md#automatic-upgrade) factoring in the [breaking changes](../migration-guide.md#major-breaking-changes) between your current version and the specified version - -In addition to running the command, we also recommend checking the [MIGRATION.md file](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md), for the detailed log of relevant changes and deprecations that might affect your upgrade. - + In addition to running the command, we also recommend checking the [MIGRATION.md file](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md), for the detailed log of relevant changes and deprecations that might affect your upgrade. ### Verifying the upgrade @@ -45,29 +37,17 @@ To help you verify that the upgrade was completed and that your project is still {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} ## Automigrate script -Storybook upgrades are not the only thing to consider: changes in the ecosystem also present challenges. For example well-known frontend frameworks, such as [Angular](https://update.angular.io/?l=2&v=16.0-17.0), [Next.js](https://nextjs.org/docs/pages/building-your-application/upgrading) or [Svelte](https://svelte.dev/docs/v4-migration-guide) have been rolling out significant changes to their ecosystem, so even if you don't upgrade your Storybook version, you might need to update your configuration accordingly. That's what Automigrate is for: +Storybook upgrades are not the only thing to consider: changes in the ecosystem also present challenges. For example well-known frontend frameworks, such as [Angular](https://update.angular.io/?l=2\&v=16.0-17.0), [Next.js](https://nextjs.org/docs/pages/building-your-application/upgrading) or [Svelte](https://svelte.dev/docs/v4-migration-guide) have been rolling out significant changes to their ecosystem, so even if you don't upgrade your Storybook version, you might need to update your configuration accordingly. That's what Automigrate is for: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -81,48 +61,32 @@ To upgrade to the latest pre-release: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} The `upgrade` command will use whichever version you specify. For example: -- `storybook@next upgrade` will upgrade to the newest pre-release version -- `storybook@8.0.0-beta.1 upgrade` will upgrade to `8.0.0-beta.1` -- `storybook@8 upgrade` will upgrade to the newest `8.x` version +* `storybook@next upgrade` will upgrade to the newest pre-release version +* `storybook@8.0.0-beta.1 upgrade` will upgrade to `8.0.0-beta.1` +* `storybook@8 upgrade` will upgrade to the newest `8.x` version If you'd like to downgrade to a stable version, manually edit the package version numbers in your `package.json` and re-install. - -Storybook collects completely anonymous data to help us improve user experience. Participation is optional, and you may [opt-out](../configure/telemetry.md#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.md#how-to-opt-out) if you'd not like to share any information. - + + ## Troubleshooting -## Troubleshooting + ### Storybook doesn't upgrade to the latest version when using Vue 2 -### Storybook doesn't upgrade to the latest version when using Vue 2 + If you're attempting to upgrade Storybook to the latest version in your existing Vue 2 project, you will no longer be able to. This is because Vue 2 entered [End of Life](https://v2.vuejs.org/lts/) (EOL) on December 31st, 2023, and will no longer receive any updates from the Vue team. We recommend you upgrade your Vue 2 project to Vue 3 and then upgrade Storybook to the latest version. If you cannot upgrade your Vue 2 project to Vue 3, you can still upgrade Storybook, but only for the latest 7.x version. You can do this by running the following command: -If you're attempting to upgrade Storybook to the latest version in your existing Vue 2 project, you will no longer be able to. This is because Vue 2 entered [End of Life](https://v2.vuejs.org/lts/) (EOL) on December 31st, 2023, and will no longer receive any updates from the Vue team. We recommend you upgrade your Vue 2 project to Vue 3 and then upgrade Storybook to the latest version. If you cannot upgrade your Vue 2 project to Vue 3, you can still upgrade Storybook, but only for the latest 7.x version. You can do this by running the following command: + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} - - - -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} diff --git a/docs/configure/user-interface.mdx b/docs/configure/user-interface.mdx index 3311289904f5..f48fdcc977e7 100644 --- a/docs/configure/user-interface.mdx +++ b/docs/configure/user-interface.mdx @@ -6,8 +6,8 @@ Storybook's UI is a highly customizable one and full of rich features to help yo Read more about the Storybook's features below: -- [Features and behaviour](./features-and-behavior.md) -- [Theming](./theming.md) -- [Storybook addons](./storybook-addons.md) -- [Sidebar & URLS](./sidebar-and-urls.md) -- [Environment variables](./environment-variables.md) +* [Features and behaviour](./features-and-behavior.md) +* [Theming](./theming.md) +* [Storybook addons](./storybook-addons.md) +* [Sidebar & URLS](./sidebar-and-urls.md) +* [Environment variables](./environment-variables.md) diff --git a/docs/configure/webpack.mdx b/docs/configure/webpack.mdx index 9077aaf235ba..06f37fd0dd71 100644 --- a/docs/configure/webpack.mdx +++ b/docs/configure/webpack.mdx @@ -18,11 +18,7 @@ You can import images and other local files and have them built into the Storybo {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -32,11 +28,7 @@ You can import `.json` files and have them expanded to a JavaScript object: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -59,11 +51,7 @@ Storybook builds your project with Webpack 4 by default. If your project uses We {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -75,11 +63,7 @@ Storybook supports Webpack's experimental [lazy compilation](https://webpack.js. {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -91,11 +75,7 @@ Storybook supports Webpack's [filesystem caching](https://webpack.js.org/configu {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -111,12 +91,7 @@ For example, if you need to adjust the config for a specific environment, you ca {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -124,18 +99,14 @@ Storybook uses the config returned from the above function to render your compon Nevertheless, edit `config` with care. Make sure to preserve the following config options: -- **entry** -- **output** +* **entry** +* **output** Furthermore, `config` requires the `HtmlWebpackplugin` to generate the preview page, so rather than overwriting `config.plugins` you should probably append to it (or overwrite it with care), see [the following issue](https://github.com/storybookjs/storybook/issues/6020) for examples on how to handle this: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -151,18 +122,12 @@ The following code snippet shows how you can replace the loaders from Storybook {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -Projects initialized via generators (e.g, Vue CLI) may require that you import their own webpack config file (i.e., /projectRoot/node_modules/@vue/cli-service/webpack.config.js) to use a certain feature with Storybook. For other generators, make sure to check the documentation for instructions. - + Projects initialized via generators (e.g, Vue CLI) may require that you import their own webpack config file (i.e., /projectRoot/node\_modules/@vue/cli-service/webpack.config.js) to use a certain feature with Storybook. For other generators, make sure to check the documentation for instructions. ### TypeScript Module Resolution @@ -171,16 +136,10 @@ When working with TypeScript projects, the default Webpack configuration may fai {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -Learn more about Storybook's built-in TypeScript support or see this issue for more information. - + Learn more about Storybook's built-in TypeScript support or see this issue for more information. diff --git a/docs/contribute/RFC.mdx b/docs/contribute/RFC.mdx index ecb3283b0946..b046ce9f120f 100644 --- a/docs/contribute/RFC.mdx +++ b/docs/contribute/RFC.mdx @@ -10,15 +10,15 @@ Many changes, such as bug fixes and documentation improvements, can be implement The purpose of the RFC (Request for Comment) process is to: -- Provide a transparent system for proposing new feature ideas. -- Establish a reliable and well-regulated process for introducing new features into the project. -- Provide a way for the community to participate in developing new features. +* Provide a transparent system for proposing new feature ideas. +* Establish a reliable and well-regulated process for introducing new features into the project. +* Provide a way for the community to participate in developing new features. ### “Feature Request” vs. “RFC” -A _feature request_ is a straightforward and relatively informal way for Storybook users to suggest a new feature or enhancement to the project. While feature requests can provide valuable insights and ideas, they typically do not involve an in-depth design process or require consensus among the core team. Feature requests are usually open to discussion and may or may not be implemented based on factors like popularity, feasibility, and alignment with the project's goals. +A *feature request* is a straightforward and relatively informal way for Storybook users to suggest a new feature or enhancement to the project. While feature requests can provide valuable insights and ideas, they typically do not involve an in-depth design process or require consensus among the core team. Feature requests are usually open to discussion and may or may not be implemented based on factors like popularity, feasibility, and alignment with the project's goals. -On the other hand, an _RFC_ is a more formalized and structured process for proposing substantial changes or additions to the project. It involves following a defined set of steps to ensure that the proposed feature or modification receives proper consideration, design, and feedback. RFCs are typically used for changes that significantly impact the project, such as introducing new API functionality, removing existing features, or establishing new usage conventions. The RFC process aims to foster discussions, gather feedback from a wider audience, and reach consensus among the core team before integrating the proposed change into the project. Accepted RFCs are more likely to be implemented than regular feature requests. +On the other hand, an *RFC* is a more formalized and structured process for proposing substantial changes or additions to the project. It involves following a defined set of steps to ensure that the proposed feature or modification receives proper consideration, design, and feedback. RFCs are typically used for changes that significantly impact the project, such as introducing new API functionality, removing existing features, or establishing new usage conventions. The RFC process aims to foster discussions, gather feedback from a wider audience, and reach consensus among the core team before integrating the proposed change into the project. Accepted RFCs are more likely to be implemented than regular feature requests. ## The RFC lifecycle @@ -26,7 +26,7 @@ On the other hand, an _RFC_ is a more formalized and structured process for prop Open a new GitHub discussion in the [“RFC” category](https://github.com/storybookjs/storybook/discussions/new?category=rfc). Fill out the form as instructed. -_Details matter_: RFCs that do not present convincing motivation, demonstrate a lack of understanding of the design's impact, or are disingenuous about the drawbacks or alternatives tend to be poorly received. +*Details matter*: RFCs that do not present convincing motivation, demonstrate a lack of understanding of the design's impact, or are disingenuous about the drawbacks or alternatives tend to be poorly received. ### 2. `Status: In review` @@ -48,8 +48,8 @@ This RFC process took heavy inspiration from the RFC processes from [Rust](https **Learn more about contributing to Storybook** -- RFC process for authoring feature requests -- [Code](./code.md) for features and bug fixes -- [Frameworks](./framework.md) to get started with a new framework -- [Documentation](./documentation-updates.md) for documentation improvements, typos, and clarifications -- [Examples](./new-snippets.md) for new snippets and examples +* RFC process for authoring feature requests +* [Code](./code.md) for features and bug fixes +* [Frameworks](./framework.md) to get started with a new framework +* [Documentation](./documentation-updates.md) for documentation improvements, typos, and clarifications +* [Examples](./new-snippets.md) for new snippets and examples diff --git a/docs/contribute/code.mdx b/docs/contribute/code.mdx index 5e8d229ae582..97f09b2b233b 100644 --- a/docs/contribute/code.mdx +++ b/docs/contribute/code.mdx @@ -6,8 +6,8 @@ Contribute a new feature or bug fix to [Storybook's monorepo](https://github.com ## Prerequisites -- Ensure you have Node version 18 installed (suggestion: v18.16.0). -- Ensure if you are using Windows to use the Windows Subsystem for Linux (WSL). +* Ensure you have Node version 18 installed (suggestion: v18.16.0). +* Ensure if you are using Windows to use the Windows Subsystem for Linux (WSL). ## Initial setup @@ -26,7 +26,7 @@ corepack enable ## Run your first sandbox -Storybook development happens in a set of _sandboxes_ which are templated Storybook environments corresponding to different user setups. Within each sandbox, we inject a set of generalized stories that allow us to test core features and addons in all such environments. +Storybook development happens in a set of *sandboxes* which are templated Storybook environments corresponding to different user setups. Within each sandbox, we inject a set of generalized stories that allow us to test core features and addons in all such environments. To run a sandbox locally, you can use the `start` command: @@ -51,9 +51,7 @@ yarn task When prompted, answer the questions as accurately as possible to allow Storybook to determine your goals. After answering these questions, you should see the entire command with the options you've selected should you require to re-run it. - -The `yarn task` command takes a few development shortcuts that can catch you off guard when switching branches and may require you to re-run both the `install` and `compile` tasks. You can speed up the process by running the command with the `start-from=install` flag. - + The `yarn task` command takes a few development shortcuts that can catch you off guard when switching branches and may require you to re-run both the `install` and `compile` tasks. You can speed up the process by running the command with the `start-from=install` flag. ## Running tests @@ -85,9 +83,7 @@ yarn build When prompted to start the build process in `watch` mode, answer **yes** to develop in interactive mode. Afterward, choose which packages you want to build. For example, if you're going to work on a feature for `@storybook/addon-docs`, you might want to select both `@storybook/addon-docs` and `@storybook/components`. - -Build's `watch` mode is great for interactive development. However, for performance reasons, it only transpiles your code and doesn't execute the TypeScript compiler. If something isn't working as expected, try running the `build` command **WITHOUT** enabling watch mode: it will re-generate TypeScript types and perform automatic type checking for you. - + Build's `watch` mode is great for interactive development. However, for performance reasons, it only transpiles your code and doesn't execute the TypeScript compiler. If something isn't working as expected, try running the `build` command **WITHOUT** enabling watch mode: it will re-generate TypeScript types and perform automatic type checking for you. ![Storybook package selector](./storybook-build-packages-selection-optimized.png) @@ -145,9 +141,7 @@ yarn test ``` - -Storybook relies on [Vitest](https://vitest.dev/) as part of it's testing suite. During the test run, if you spot that snapshot tests are failing, re-run the command with the `-u` flag to update them. - + Storybook relies on [Vitest](https://vitest.dev/) as part of it's testing suite. During the test run, if you spot that snapshot tests are failing, re-run the command with the `-u` flag to update them. Doing this prevents last-minute bugs and is a great way to merge your contribution faster once you submit your pull request. Failing to do so will lead to one of the maintainers mark the pull request with the **Work in Progress** label until all tests pass. @@ -160,8 +154,8 @@ If your contribution focuses on a bugfix and you want it featured in the next st #### Useful resources when working with forks -- [Sync a fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/syncing-a-fork) -- [Merge an upstream repository into your fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork) +* [Sync a fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/syncing-a-fork) +* [Merge an upstream repository into your fork](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks/merging-an-upstream-repository-into-your-fork) ### Reproducing job failures @@ -174,11 +168,9 @@ yarn task --task e2e-tests --template=react-vite/default-ts --start-from=install Typically it is a good idea to start from the `install` task to ensure your local code is completely up to date. If you reproduce the failure, you can try and make fixes, [compile them](#start-developing) with `build`, then rerun the task with `--start-from=auto`. + The default instructions run the code in "linked" mode, meaning built changes to Storybook library code will be reflected in the sandbox immediately (the next time you run the task). However, CI runs in "unlinked" mode, which in rare cases, will behave differently. -The default instructions run the code in "linked" mode, meaning built changes to Storybook library code will be reflected in the sandbox immediately (the next time you run the task). However, CI runs in "unlinked" mode, which in rare cases, will behave differently. - -If you are having trouble reproducing, try rerunning the command with the `--no-link` flag. If you need to do that, you'll need to run it with `--start-from=compile` after each code change. - + If you are having trouble reproducing, try rerunning the command with the `--no-link` flag. If you need to do that, you'll need to run it with `--start-from=compile` after each code change. ## How to work with reproductions @@ -200,9 +192,7 @@ npx storybook@next link --local /path/to/local-repro-directory ``` - -The `storybook link` command relies on [Yarn linking](https://yarnpkg.com/cli/link/) under the hood. It requires your local reproduction to be using [Yarn 2 or higher](https://yarnpkg.com/) as well, which is the case if you've already enabled it with the [`storybook sandbox`](./how-to-reproduce.md) command per our contribution guidelines. The process will fail if you're trying to link a non-Yarn 2 project. - + The `storybook link` command relies on [Yarn linking](https://yarnpkg.com/cli/link/) under the hood. It requires your local reproduction to be using [Yarn 2 or higher](https://yarnpkg.com/) as well, which is the case if you've already enabled it with the [`storybook sandbox`](./how-to-reproduce.md) command per our contribution guidelines. The process will fail if you're trying to link a non-Yarn 2 project. ## Developing a template @@ -226,8 +216,8 @@ Add the `inDevelopment` flag until the PR is merged (you can fast-follow it with The **`key`** `cra/default-js` consists of two parts: -- The prefix is the tool that was used to generate the repro app -- The suffix is options that modify the default install, e.g. a specific version or options +* The prefix is the tool that was used to generate the repro app +* The suffix is options that modify the default install, e.g. a specific version or options The **`script`** field is what generates the application environment. The `.` argument is “the current working directory” which is auto-generated based on the key (e.g. `repros/cra/default-js/before-storybook`). The `{{beforeDir}}` key can also be used, which will be replaced by the path of that directory. @@ -254,17 +244,15 @@ Once the PR is merged, the template will be generated on a nightly cadence and y ## Troubleshooting
+ yarn build --all --watch watches everything but is resource-intensive -yarn build --all --watch watches everything but is resource-intensive - -It's troublesome to know which packages you'll change ahead of time, and watching them can be highly demanding, even on modern machines. If you're working on a powerful enough machine, you can use `yarn build --all --watch` instead of `yarn build`. - + It's troublesome to know which packages you'll change ahead of time, and watching them can be highly demanding, even on modern machines. If you're working on a powerful enough machine, you can use `yarn build --all --watch` instead of `yarn build`.
**Learn more about contributing to Storybook** -- [RFC process](./RFC.md) for authoring feature requests -- Code for features and bug fixes -- [Frameworks](./framework.md) to get started with a new framework -- [Documentation](./documentation-updates.md) for documentation improvements, typos, and clarifications -- [Examples](./new-snippets.md) for new snippets and examples +* [RFC process](./RFC.md) for authoring feature requests +* Code for features and bug fixes +* [Frameworks](./framework.md) to get started with a new framework +* [Documentation](./documentation-updates.md) for documentation improvements, typos, and clarifications +* [Examples](./new-snippets.md) for new snippets and examples diff --git a/docs/contribute/documentation-updates.mdx b/docs/contribute/documentation-updates.mdx index d73d9d8f3070..5835a4f10d41 100644 --- a/docs/contribute/documentation-updates.mdx +++ b/docs/contribute/documentation-updates.mdx @@ -24,8 +24,8 @@ In the Storybook repository, create a pull request that describes changes and in **Learn more about contributing to Storybook** -- [RFC process](./RFC.md) for authoring feature requests -- [Code](./code.md) for features and bug fixes -- [Frameworks](./framework.md) to get started with a new framework -- Documentation for documentation improvements, typos, and clarifications -- [Examples](./new-snippets.md) for new snippets and examples +* [RFC process](./RFC.md) for authoring feature requests +* [Code](./code.md) for features and bug fixes +* [Frameworks](./framework.md) to get started with a new framework +* Documentation for documentation improvements, typos, and clarifications +* [Examples](./new-snippets.md) for new snippets and examples diff --git a/docs/contribute/framework.mdx b/docs/contribute/framework.mdx index f54e19bae401..cb789721897f 100644 --- a/docs/contribute/framework.mdx +++ b/docs/contribute/framework.mdx @@ -35,92 +35,91 @@ A framework can contain the following parts: Because a framework is a node package, it must contain a `package.json` file. Here’s a template you can use to start:
-package.json template - -```json -{ - "name": "", - "version": "1.0.0", - "description": "Storybook for or & ", - "keywords": [ - "Storybook", - "", - "", - "", - "", - "", - "" - ], - "homepage": "", - "bugs": { - "url": "https://github.com///issues" - }, - "repository": { - "type": "git", - "url": "https://github.com//.git", - "directory": "" - }, - "license": "MIT", - "exports": { - ".": { - "types": "./dist/index.d.ts", - "require": "./dist/index.js", - "import": "./dist/index.mjs" + package.json template + + ```json + { + "name": "", + "version": "1.0.0", + "description": "Storybook for or & ", + "keywords": [ + "Storybook", + "", + "", + "", + "", + "", + "" + ], + "homepage": "", + "bugs": { + "url": "https://github.com///issues" }, - "./preset": { - "types": "./dist/preset.d.ts", - "require": "./dist/preset.js", - "import": "./dist/preset.mjs" + "repository": { + "type": "git", + "url": "https://github.com//.git", + "directory": "" }, - "./preview.js": { - "types": "./dist/preview.d.ts", - "require": "./dist/preview.js", - "import": "./dist/preview.mjs" + "license": "MIT", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "require": "./dist/index.js", + "import": "./dist/index.mjs" + }, + "./preset": { + "types": "./dist/preset.d.ts", + "require": "./dist/preset.js", + "import": "./dist/preset.mjs" + }, + "./preview.js": { + "types": "./dist/preview.d.ts", + "require": "./dist/preview.js", + "import": "./dist/preview.mjs" + }, + "./package.json": "./package.json" }, - "./package.json": "./package.json" - }, - "main": "dist/index.js", - "module": "dist/index.mjs", - "types": "dist/index.d.ts", - "files": ["dist/**/*", "types/**/*", "README.md", "*.js", "*.d.ts"], - "scripts": { - "check": "tsc --noEmit", - "test": "..." - }, - "dependencies": { - "@storybook/manager-api": "^7.0.0", - "@storybook/core-common": "^7.0.0", - "@storybook/node-logger": "^7.0.0", - "@storybook/": "^7.0.0", - "@storybook/": "^7.0.0" - }, - "devDependencies": { - "typescript": "x.x.x", - "": "^x.x.x", - "": "^x.x.x" - }, - "peerDependencies": { - "@storybook/addon-actions": "^7.0.0", - "": "^x.x.x || ^x.x.x", - "": "^x.x.x || ^x.x.x", - "": "^x.x.x" - }, - "engines": { - "node": ">=18.0.0" - }, - "publishConfig": { - "access": "public" + "main": "dist/index.js", + "module": "dist/index.mjs", + "types": "dist/index.d.ts", + "files": ["dist/**/*", "types/**/*", "README.md", "*.js", "*.d.ts"], + "scripts": { + "check": "tsc --noEmit", + "test": "..." + }, + "dependencies": { + "@storybook/manager-api": "^7.0.0", + "@storybook/core-common": "^7.0.0", + "@storybook/node-logger": "^7.0.0", + "@storybook/": "^7.0.0", + "@storybook/": "^7.0.0" + }, + "devDependencies": { + "typescript": "x.x.x", + "": "^x.x.x", + "": "^x.x.x" + }, + "peerDependencies": { + "@storybook/addon-actions": "^7.0.0", + "": "^x.x.x || ^x.x.x", + "": "^x.x.x || ^x.x.x", + "": "^x.x.x" + }, + "engines": { + "node": ">=18.0.0" + }, + "publishConfig": { + "access": "public" + } } -} -``` - -A few notes on some of those properties: + ``` -- `exports`: The root, `./preset`, and `package.json` exports are required. If your framework has a `preview.js`, then that is required as well. -- `types`: We strongly encourage you to author your framework in TypeScript and distribute the types. -- `dependencies` and `devDependencies`: These are just examples. Yours may look quite different. -- `peerDependencies`: If your framework provides support for multiple versions of the libraries you’re targeting, be sure that is represented here. + A few notes on some of those properties: + * `exports`: The root, `./preset`, and `package.json` exports are required. If your framework has a `preview.js`, then that is required as well. + * `types`: We strongly encourage you to author your framework in TypeScript and distribute the types. + * `dependencies` and `devDependencies`: These are just examples. Yours may look quite different. + * `peerDependencies`: If your framework provides support for multiple versions of the libraries you’re targeting, be sure that is represented here.
#### `preset.js` ([example](https://github.com/storybookjs/storybook/blob/next/code/frameworks/nextjs/src/preset.ts)) @@ -145,8 +144,8 @@ Once it's fully tested and released, please let us know about your framework by **Learn more about contributing to Storybook** -- [RFC process](./RFC.md) for authoring feature requests -- [Code](./code.md) for features and bug fixes -- Frameworks to get started with a new framework -- [Documentation](./documentation-updates.md) for documentation improvements, typos, and clarifications -- [Examples](./new-snippets.md) for new snippets and examples +* [RFC process](./RFC.md) for authoring feature requests +* [Code](./code.md) for features and bug fixes +* Frameworks to get started with a new framework +* [Documentation](./documentation-updates.md) for documentation improvements, typos, and clarifications +* [Examples](./new-snippets.md) for new snippets and examples diff --git a/docs/contribute/how-to-reproduce.mdx b/docs/contribute/how-to-reproduce.mdx index 95d81b691903..e5f9062008f0 100644 --- a/docs/contribute/how-to-reproduce.mdx +++ b/docs/contribute/how-to-reproduce.mdx @@ -12,9 +12,9 @@ A reproducible test case is a great way to share a specific set of conditions th Make sure you have: -- Installed [`Yarn`](https://yarnpkg.com/) on your local development machine. -- A [GitHub account](https://github.com/signup) for hosting the reproduction's code. -- A [Chromatic account](https://www.chromatic.com/start/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) for publishing your Storybook. +* Installed [`Yarn`](https://yarnpkg.com/) on your local development machine. +* A [GitHub account](https://github.com/signup) for hosting the reproduction's code. +* A [Chromatic account](https://www.chromatic.com/start/?utm_source=storybook_website\&utm_medium=link\&utm_campaign=storybook) for publishing your Storybook. ## Initial setup @@ -25,9 +25,7 @@ npx storybook@next sandbox ``` - -You can append a template name in the command to get filtered results (e.g., `npx storybook@next sandbox react`). - + You can append a template name in the command to get filtered results (e.g., `npx storybook@next sandbox react`). Next, choose the template you want to work with: @@ -39,9 +37,7 @@ Finally, enter a location for your reproduction: ![Storybook reproduction location](./storybook-reproduction-generator-location.png) - -If you don't provide a full path for the reproduction it will be generated in the current directory. - + If you don't provide a full path for the reproduction it will be generated in the current directory. If everything worked as it should, you should have a fully functional Storybook set up in your local environment. @@ -67,21 +63,19 @@ Then, follow GitHub's instructions to set up the repository. ![github repository instructions](./github-repository-steps-optimized.png) - -Don't forget to replace `your-username` with your own account name. - + Don't forget to replace `your-username` with your own account name. ## Publish -An excellent way to check your reproduction is to have it deployed online. We recommend [Chromatic](https://www.chromatic.com/?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook), a free publishing service created by the Storybook maintainers. It allows you to deploy and host your reproduction safely and securely in the cloud. +An excellent way to check your reproduction is to have it deployed online. We recommend [Chromatic](https://www.chromatic.com/?utm_source=storybook_website\&utm_medium=link\&utm_campaign=storybook), a free publishing service created by the Storybook maintainers. It allows you to deploy and host your reproduction safely and securely in the cloud. ### Helpful resources when working with Chromatic -- [Publish Storybook](../sharing/publish-storybook.md) -- [Setup Chromatic](https://www.chromatic.com/docs/setup?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) -- [Automate Chromatic with continuous integration](https://www.chromatic.com/docs/ci?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook) +* [Publish Storybook](../sharing/publish-storybook.md) +* [Setup Chromatic](https://www.chromatic.com/docs/setup?utm_source=storybook_website\&utm_medium=link\&utm_campaign=storybook) +* [Automate Chromatic with continuous integration](https://www.chromatic.com/docs/ci?utm_source=storybook_website\&utm_medium=link\&utm_campaign=storybook) ## Submit the issue -Finally, create your issue in the [Storybook issue tracker](https://github.com/storybookjs/storybook/issues/new/choose), go through the required steps, and provide a detailed description of the problem. Add the GitHub repository and [deployed reproduction](https://www.chromatic.com/docs/setup?utm_source=storybook_website&utm_medium=link&utm_campaign=storybook#view-published-storybook) to help with the triage process. +Finally, create your issue in the [Storybook issue tracker](https://github.com/storybookjs/storybook/issues/new/choose), go through the required steps, and provide a detailed description of the problem. Add the GitHub repository and [deployed reproduction](https://www.chromatic.com/docs/setup?utm_source=storybook_website\&utm_medium=link\&utm_campaign=storybook#view-published-storybook) to help with the triage process. diff --git a/docs/contribute/index.mdx b/docs/contribute/index.mdx index db49e426fa17..7e0b972d3f41 100644 --- a/docs/contribute/index.mdx +++ b/docs/contribute/index.mdx @@ -11,15 +11,15 @@ In the interest of fostering an open and welcoming environment, we as contributo ## Ways to contribute -- [**RFC process**](./RFC.md) for authoring feature requests -- [**Code**](./code.md) for features and bug fixes -- [**Frameworks**](./framework.md) to get started with a new framework -- [**Documentation**](./documentation-updates.md) for documentation improvements, typos, and clarifications -- [**Examples**](./new-snippets.md) for new snippets and examples -- [**Addons**](./../addons/index.md) for new addons +* [**RFC process**](./RFC.md) for authoring feature requests +* [**Code**](./code.md) for features and bug fixes +* [**Frameworks**](./framework.md) to get started with a new framework +* [**Documentation**](./documentation-updates.md) for documentation improvements, typos, and clarifications +* [**Examples**](./new-snippets.md) for new snippets and examples +* [**Addons**](./../addons/index.md) for new addons ## Not sure how to get started? -- [Chat in Discord `#contributing`](https://discord.com/channels/486522875931656193/839297503446695956) -- [Browse "good first issues" to fix](https://github.com/storybookjs/storybook/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) -- [Submit a bug report or feature request](https://github.com/storybookjs/storybook/issues) +* [Chat in Discord `#contributing`](https://discord.com/channels/486522875931656193/839297503446695956) +* [Browse "good first issues" to fix](https://github.com/storybookjs/storybook/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) +* [Submit a bug report or feature request](https://github.com/storybookjs/storybook/issues) diff --git a/docs/contribute/new-snippets.mdx b/docs/contribute/new-snippets.mdx index e3d5ba2976e1..f90473563be0 100644 --- a/docs/contribute/new-snippets.mdx +++ b/docs/contribute/new-snippets.mdx @@ -84,9 +84,7 @@ Create the file `ember/your-component.js.mdx`, similar to the other frameworks, ``` - -Code snippets are divided into various file extensions, if you're contributing a TypeScript file use `.ts.mdx`, or if you're adding JavaScript files use `.js.mdx`. - + Code snippets are divided into various file extensions, if you're contributing a TypeScript file use `.ts.mdx`, or if you're adding JavaScript files use `.js.mdx`. Go through the rest of the documentation and repeat the process. @@ -114,9 +112,7 @@ yarn start:docs-only ``` - -During the start process if there's an issue with the documentation, the process will stop and you'll get a notification. - + During the start process if there's an issue with the documentation, the process will stop and you'll get a notification. Open a browser window to `http://localhost:8000`, click the Docs link, and select your framework from the dropdown. @@ -131,8 +127,8 @@ Finally, commit, push and open a pull request in the Storybook monorepo. Add a c **Learn more about contributing to Storybook** -- [RFC process](./RFC.md) for authoring feature requests -- [Code](./code.md) for features and bug fixes -- [Frameworks](./framework.md) to get started with a new framework -- [Documentation](./documentation-updates.md) for documentation improvements, typos, and clarifications -- [Examples](./new-snippets.md) for new snippets and examples +* [RFC process](./RFC.md) for authoring feature requests +* [Code](./code.md) for features and bug fixes +* [Frameworks](./framework.md) to get started with a new framework +* [Documentation](./documentation-updates.md) for documentation improvements, typos, and clarifications +* [Examples](./new-snippets.md) for new snippets and examples diff --git a/docs/essentials/actions.mdx b/docs/essentials/actions.mdx index 694ba56d91f7..f686cfa85447 100644 --- a/docs/essentials/actions.mdx +++ b/docs/essentials/actions.mdx @@ -7,10 +7,7 @@ title: 'Actions' The actions addon is used to display data received by event handler (callback) arguments in your stories. ## Action args @@ -23,13 +20,7 @@ The recommended way to write actions is to use the `fn` utility from `@storybook {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -45,12 +36,7 @@ This is quite useful when your component has dozens (or hundreds) of methods and {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -58,22 +44,12 @@ If you need more granular control over which `argTypes` are matched, you can adj {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -If you're generating argTypes with another addon (like [docs](../writing-docs/index.md), which is the common behavior), ensure the actions addon **AFTER** the other addon. You can do this by listing it later in the addons registration code in [`.storybook/main.js`](../configure/index.md#configure-story-rendering). This is default in [essentials](./index.md). - + If you're generating argTypes with another addon (like [docs](../writing-docs/index.md), which is the common behavior), ensure the actions addon **AFTER** the other addon. You can do this by listing it later in the addons registration code in [`.storybook/main.js`](../configure/index.md#configure-story-rendering). This is default in [essentials](./index.md). ## Action event handlers @@ -82,16 +58,7 @@ It is also possible to detect if your component is emitting the correct HTML eve {/* prettier-ignore-start */} - - + {/* prettier-ignore-end */} @@ -141,15 +108,7 @@ Allows you to create an action that appears in the actions panel of the Storyboo {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/essentials/backgrounds.mdx b/docs/essentials/backgrounds.mdx index 516a7b86cdbb..0d3fa150bf68 100644 --- a/docs/essentials/backgrounds.mdx +++ b/docs/essentials/backgrounds.mdx @@ -5,10 +5,7 @@ title: 'Backgrounds' The backgrounds toolbar addon allows you to set the background color in which the story renders in the UI: ## Configuration @@ -19,12 +16,7 @@ But you're not restricted to these backgrounds, you can configure your own set o {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -36,15 +28,7 @@ You can also define backgrounds per-component or per-story basis through [parame {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -52,17 +36,7 @@ You can also override a single key on the `backgrounds` parameter, for instance, {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -72,17 +46,7 @@ If you want to disable backgrounds in a story, you can do so by setting the `bac {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -94,15 +58,7 @@ You don't need additional configuration to get started. But its properties are f {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -112,17 +68,7 @@ If you need to disable the grid for a specific story, set the `backgrounds` para {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/essentials/controls.mdx b/docs/essentials/controls.mdx index ccd0155ebca3..e772fb18526b 100644 --- a/docs/essentials/controls.mdx +++ b/docs/essentials/controls.mdx @@ -7,240 +7,148 @@ title: 'Controls' Storybook Controls gives you a graphical UI to interact with a component's arguments dynamically without needing to code. It creates an addon panel next to your component examples ("stories"), so you can edit them live. Controls do not require any modification to your components. Stories for controls are: -- Convenient. Auto-generate controls based on React/Vue/Angular/etc. components. -- Portable. Reuse your interactive stories in documentation, tests, and even in designs. -- Rich. Customize the controls and interactive data to suit your exact needs. +* Convenient. Auto-generate controls based on React/Vue/Angular/etc. components. +* Portable. Reuse your interactive stories in documentation, tests, and even in designs. +* Rich. Customize the controls and interactive data to suit your exact needs. To use the Controls addon, you need to write your stories using [args](../writing-stories/args.md). Storybook will automatically generate UI controls based on your args and what it can infer about your component. Still, you can configure the controls further using [argTypes](../api/arg-types.md), see below. - -If you have stories in the older pre-Storybook 6 style, check the [args & controls migration guide](https://medium.com/storybookjs/storybook-6-migration-guide-200346241bb5) to learn how to convert your existing stories for args. - + If you have stories in the older pre-Storybook 6 style, check the [args & controls migration guide](https://medium.com/storybookjs/storybook-6-migration-guide-200346241bb5) to learn how to convert your existing stories for args. ## Choosing the control type - + + By default, Storybook will try to infer the required argTypes and associated controls for your stories based on the component's definition and initial value of the args using [Compodoc](https://compodoc.app/), a documentation generator for Angular applications that can extract the metadata of your components, including first-class support for Angular's `inputs`, `outputs`, `properties`, `methods`, and `view/content child/children`. If you opt-in to use it, you must take additional steps to set it up properly. -By default, Storybook will try to infer the required argTypes and associated controls for your stories based on the component's definition and initial value of the args using [Compodoc](https://compodoc.app/), a documentation generator for Angular applications that can extract the metadata of your components, including first-class support for Angular's `inputs`, `outputs`, `properties`, `methods`, and `view/content child/children`. If you opt-in to use it, you must take additional steps to set it up properly. + Run the following command to install the tooling. -Run the following command to install the tooling. + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} + - + {/* prettier-ignore-end */} -{/* prettier-ignore-end */} + Update your `angular.json` file to include the following configuration to include it in the Storybook's inbuilt builder configuration. -Update your `angular.json` file to include the following configuration to include it in the Storybook's inbuilt builder configuration. + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} + - + {/* prettier-ignore-end */} + Finally, update your `.storybook/preview.ts` file to include the following configuration to import the metadata generated by Compodoc and use it to generate the controls and argTypes for your stories. -{/* prettier-ignore-end */} - -Finally, update your `.storybook/preview.ts` file to include the following configuration to import the metadata generated by Compodoc and use it to generate the controls and argTypes for your stories. + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} + - + {/* prettier-ignore-end */} + When you set the `component` annotation of the default export of your story file, it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component. -{/* prettier-ignore-end */} + {/* prettier-ignore-start */} -When you set the `component` annotation of the default export of your story file, it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component. - -{/* prettier-ignore-start */} - - - -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} - - -By default, Storybook will try to infer the required argTypes and associated controls for your stories based on the metadata provided by the [`@storybook/ember-cli-storybook`](https://github.com/storybookjs/ember-cli-storybook) adapter. You'll need to take some additional steps to set it up properly. - -Update your `ember-cli-build.js` configuration file to include the adapter. - -{/* prettier-ignore-start */} + + By default, Storybook will try to infer the required argTypes and associated controls for your stories based on the metadata provided by the [`@storybook/ember-cli-storybook`](https://github.com/storybookjs/ember-cli-storybook) adapter. You'll need to take some additional steps to set it up properly. - + Update your `ember-cli-build.js` configuration file to include the adapter. -{/* prettier-ignore-end */} + {/* prettier-ignore-start */} -Restart your application to generate the metadata file (i.e., `storybook-docgen/index.json`) and update your `.storybook/preview.js` file to include it, which will be used to create the controls and argTypes for your stories. + -{/* prettier-ignore-start */} + {/* prettier-ignore-end */} - + Restart your application to generate the metadata file (i.e., `storybook-docgen/index.json`) and update your `.storybook/preview.js` file to include it, which will be used to create the controls and argTypes for your stories. -{/* prettier-ignore-end */} + {/* prettier-ignore-start */} - + -Enabling this feature will generate a `storybook-docgen/index.json` automatically with each build. For more information on how the metadata is generated, refer to [documentation](https://github.com/storybookjs/storybook/tree/next/code/frameworks/ember) for the Ember framework. + {/* prettier-ignore-end */} - + + Enabling this feature will generate a `storybook-docgen/index.json` automatically with each build. For more information on how the metadata is generated, refer to [documentation](https://github.com/storybookjs/storybook/tree/next/code/frameworks/ember) for the Ember framework. + -When you set the `component` annotation of the default export of your story file, it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component. + When you set the `component` annotation of the default export of your story file, it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component. -{/* prettier-ignore-start */} - - + {/* prettier-ignore-start */} -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} - + + By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component using [`react-docgen`](https://github.com/reactjs/react-docgen), a documentation generator for React components that also includes first-class support for TypeScript. -By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component using [`react-docgen`](https://github.com/reactjs/react-docgen), a documentation generator for React components that also includes first-class support for TypeScript. + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} - - - -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} - - -By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component using [`vue-docgen-api`](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api), including first-class support for Vue's `props`, `events`, and `slots`. + + By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component using [`vue-docgen-api`](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-api), including first-class support for Vue's `props`, `events`, and `slots`. -{/* prettier-ignore-start */} - - + {/* prettier-ignore-start */} -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} - + + By default, Storybook will try to infer the required argTypes and associated controls for your stories based on the component's definition and the initial value of the args. You'll need to take some additional steps to set it up properly. You can opt to generate a [`custom-elements.json`](https://github.com/webcomponents/custom-elements-json) file with [`@custom-elements-manifest/analyzer`](https://github.com/open-wc/custom-elements-manifest) if you're using the `pre-v1.0.0` version of the elements file or [`@custom-elements-manifest/analyzer`](https://github.com/open-wc/custom-elements-manifest/tree/master/packages/analyzer) for newer versions and configure it in your Storybook UI configuration file (i.e., `.storybook/preview.js|ts`) to enable it. -By default, Storybook will try to infer the required argTypes and associated controls for your stories based on the component's definition and the initial value of the args. You'll need to take some additional steps to set it up properly. You can opt to generate a [`custom-elements.json`](https://github.com/webcomponents/custom-elements-json) file with [`@custom-elements-manifest/analyzer`](https://github.com/open-wc/custom-elements-manifest) if you're using the `pre-v1.0.0` version of the elements file or [`@custom-elements-manifest/analyzer`](https://github.com/open-wc/custom-elements-manifest/tree/master/packages/analyzer) for newer versions and configure it in your Storybook UI configuration file (i.e., `.storybook/preview.js|ts`) to enable it. + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} + - + {/* prettier-ignore-end */} + When you set the `component` annotation of the default export of your story file, it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component. -{/* prettier-ignore-end */} - -When you set the `component` annotation of the default export of your story file, it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component. + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} - - - -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} + By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component provided by the framework you've chosen to use. -By default, Storybook will choose a control for each arg based on its initial value. This will work well with specific arg types (e.g., `boolean` or `string`). To enable them, add the `component` annotation to the default export of your story file, and it will be used to infer the controls and auto-generate the matching [`argTypes`](../api/arg-types.md) for your component provided by the framework you've chosen to use. - -{/* prettier-ignore-start */} + {/* prettier-ignore-start */} - + -{/* prettier-ignore-end */} - - - -If you're using a framework that doesn't support this feature, you'll need to define the `argTypes` for your component [manually](#fully-custom-args). - - + {/* prettier-ignore-end */} + + If you're using a framework that doesn't support this feature, you'll need to define the `argTypes` for your component [manually](#fully-custom-args). + For instance, suppose you have a `variant` arg on your story that should be `primary` or `secondary`: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -256,23 +164,12 @@ We can specify which controls get used by declaring a custom [argType](../api/ar {/* prettier-ignore-start */} - - + {/* prettier-ignore-end */} - -ArgTypes are a powerful feature that can be used to customize the controls for your stories. For more information, see the documentation about [customizing controls](#annotation) with `argTypes` annotation. - + ArgTypes are a powerful feature that can be used to customize the controls for your stories. For more information, see the documentation about [customizing controls](#annotation) with `argTypes` annotation. This replaces the input with a radio group for a more intuitive experience. @@ -285,58 +182,37 @@ Controls can automatically be inferred from arg's name with [regex](https://deve | Control | Default regex | Description | | --------- | ---------------------------------------- | --------------------------------------------------------- | -| **color** | /(background|color)$/i | Will display a color picker UI for the args that match it | +| **color** | /(background|color)$/i | Will display a color picker UI for the args that match it | | **date** | `/Date$/` | Will display a date picker UI for the args that match it | If you haven't used the CLI to set the configuration, or if you want to define your patterns, use the `matchers` property in the `controls` parameter: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} + {/* Uncomment once frameworks that support custom templates are enabled to prevent misinformation about the example */} -{/* Uncomment once frameworks that support custom templates are enabled to prevent misinformation about the example */} + ## Fully custom args -## Fully custom args + Until now, we only used auto-generated controls based on the component for which we're writing stories. If we are writing [complex stories](../writing-stories/stories-for-multiple-components.md), we may want to add controls for args that aren’t part of the component. For example, here's how you could use a `footer` arg to populate a child component: -Until now, we only used auto-generated controls based on the component for which we're writing stories. If we are writing [complex stories](../writing-stories/stories-for-multiple-components.md), we may want to add controls for args that aren’t part of the component. For example, here's how you could use a `footer` arg to populate a child component: + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} + - + {/* prettier-ignore-end */} -{/* prettier-ignore-end */} - -By default, Storybook will add controls for all args that: + By default, Storybook will add controls for all args that: -- It infers from the component definition [if your framework supports it](../configure/frameworks-feature-support.md). + * It infers from the component definition [if your framework supports it](../configure/frameworks-feature-support.md). -- Appear in the list of args for your story. - -Using `argTypes`, you can change the display and behavior of each control. + * Appear in the list of args for your story. + Using `argTypes`, you can change the display and behavior of each control. ### Dealing with complex values @@ -347,23 +223,7 @@ One way to deal with this is to use primitive values (e.g., strings) as arg valu {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -371,15 +231,7 @@ Unless you need the flexibility of a function, an easier way to map primitives t {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -394,23 +246,15 @@ The Controls addon allows you to create or edit stories, directly from the Contr Open the Controls panel for a story and adjust the value of a control. Then save those changes as a new story. + If you're working on a component that does not yet have any stories, you can click the ➕ button in the sidebar to search for your component and have a basic story created for you. -If you're working on a component that does not yet have any stories, you can click the ➕ button in the sidebar to search for your component and have a basic story created for you. - - - + ### Edit a story @@ -418,18 +262,15 @@ If you're working on a component that does not yet have any stories, you can cli You can also update a control's value, then save the changes to the story. The story file's code will be updated for you. ## Configuration The Controls addon can be configured in two ways: -- Individual controls can be configured via control annotations. -- The addon's appearance can be configured via parameters. +* Individual controls can be configured via control annotations. +* The addon's appearance can be configured via parameters. ### Annotation @@ -437,47 +278,34 @@ As shown above, you can configure individual controls with the “control" annot | Data Type | Control | Description | | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **boolean** | `boolean` | Provides a toggle for switching between possible states.
`argTypes: { active: { control: 'boolean' }}` | -| **number** | `number` | Provides a numeric input to include the range of all possible values.
`argTypes: { even: { control: { type: 'number', min:1, max:30, step: 2 } }}` | -| | `range` | Provides a range slider component to include all possible values.
`argTypes: { odd: { control: { type: 'range', min: 1, max: 30, step: 3 } }}` | -| **object** | `object` | Provides a JSON-based editor component to handle the object's values.
Also allows edition in raw mode.
`argTypes: { user: { control: 'object' }}` | -| **array** | `object` | Provides a JSON-based editor component to handle the array's values.
Also allows edition in raw mode.
`argTypes: { odd: { control: 'object' }}` | -| | `file` | Provides a file input component that returns an array of URLs.
Can be further customized to accept specific file types.
`argTypes: { avatar: { control: { type: 'file', accept: '.png' } }}` | -| **enum** | `radio` | Provides a set of radio buttons based on the available options.
`argTypes: { contact: { control: 'radio', options: ['email', 'phone', 'mail'] }}` | -| | `inline-radio` | Provides a set of inlined radio buttons based on the available options.
`argTypes: { contact: { control: 'inline-radio', options: ['email', 'phone', 'mail'] }}` | -| | `check` | Provides a set of checkbox components for selecting multiple options.
`argTypes: { contact: { control: 'check', options: ['email', 'phone', 'mail'] }}` | -| | `inline-check` | Provides a set of inlined checkbox components for selecting multiple options.
`argTypes: { contact: { control: 'inline-check', options: ['email', 'phone', 'mail'] }}` | +| **boolean** | `boolean` | Provides a toggle for switching between possible states.
`argTypes: { active: { control: 'boolean' }}` | +| **number** | `number` | Provides a numeric input to include the range of all possible values.
`argTypes: { even: { control: { type: 'number', min:1, max:30, step: 2 } }}` | +| | `range` | Provides a range slider component to include all possible values.
`argTypes: { odd: { control: { type: 'range', min: 1, max: 30, step: 3 } }}` | +| **object** | `object` | Provides a JSON-based editor component to handle the object's values.
Also allows edition in raw mode.
`argTypes: { user: { control: 'object' }}` | +| **array** | `object` | Provides a JSON-based editor component to handle the array's values.
Also allows edition in raw mode.
`argTypes: { odd: { control: 'object' }}` | +| | `file` | Provides a file input component that returns an array of URLs.
Can be further customized to accept specific file types.
`argTypes: { avatar: { control: { type: 'file', accept: '.png' } }}` | +| **enum** | `radio` | Provides a set of radio buttons based on the available options.
`argTypes: { contact: { control: 'radio', options: ['email', 'phone', 'mail'] }}` | +| | `inline-radio` | Provides a set of inlined radio buttons based on the available options.
`argTypes: { contact: { control: 'inline-radio', options: ['email', 'phone', 'mail'] }}` | +| | `check` | Provides a set of checkbox components for selecting multiple options.
`argTypes: { contact: { control: 'check', options: ['email', 'phone', 'mail'] }}` | +| | `inline-check` | Provides a set of inlined checkbox components for selecting multiple options.
`argTypes: { contact: { control: 'inline-check', options: ['email', 'phone', 'mail'] }}` | | | `select` | Provides a drop-down list component to handle single value selection. `argTypes: { age: { control: 'select', options: [20, 30, 40, 50] }}` | | | `multi-select` | Provides a drop-down list that allows multiple selected values. `argTypes: { countries: { control: 'multi-select', options: ['USA', 'Canada', 'Mexico'] }}` | -| **string** | `text` | Provides a freeform text input.
`argTypes: { label: { control: 'text' }}` | -| | `color` | Provides a color picker component to handle color values.
Can be additionally configured to include a set of color presets.
`argTypes: { color: { control: { type: 'color', presetColors: ['red', 'green']} }}` | +| **string** | `text` | Provides a freeform text input.
`argTypes: { label: { control: 'text' }}` | +| | `color` | Provides a color picker component to handle color values.
Can be additionally configured to include a set of color presets.
`argTypes: { color: { control: { type: 'color', presetColors: ['red', 'green']} }}` | | | `date` | Provides a datepicker component to handle date selection. `argTypes: { startDate: { control: 'date' }}` | - -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. {/* prettier-ignore-start */} - - + {/* prettier-ignore-end */} - -Numeric data types will default to a `number` control unless additional configuration is provided. - + Numeric data types will default to a `number` control unless additional configuration is provided. ### Parameters @@ -492,12 +320,7 @@ To enable expanded mode globally, add the following to [`.storybook/preview.js`] {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -511,12 +334,7 @@ For `color` controls, you can specify an array of `presetColors`, either on the {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -532,17 +350,7 @@ Consider the following story snippets: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -554,15 +362,7 @@ Consider the following snippet to force required args first: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -574,47 +374,26 @@ Suppose you want to turn off Controls for a property called `foo` in a component {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} Resulting in the following change in Storybook UI: The previous example also removed the prop documentation from the table. In some cases, this is fine. However, sometimes you might want to render the prop documentation without a control. The following example illustrates how: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -As with other Storybook properties, such as [decorators](../writing-stories/decorators.md), you can apply the same pattern at a story level for more granular cases. - + As with other Storybook properties, such as [decorators](../writing-stories/decorators.md), you can apply the same pattern at a story level for more granular cases. ### Conditional controls @@ -625,15 +404,7 @@ Consider a collection of "advanced" settings only visible when the user toggles {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -641,15 +412,7 @@ Or consider a constraint where if the user sets one control value, it doesn't ma {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -672,13 +435,11 @@ It may also contain at most one of the following operators: If no operator is provided, that is equivalent to `{ truthy: true }`. + ## Troubleshooting -## Troubleshooting - -### Controls are not automatically generated for my component - -If you're working with Angular, Ember, or Web Components, automatic argTypes and controls inference will not work out of the box and requires you to provide [additional configuration](#choosing-the-control-type) to allow Storybook to retrieve the necessary metadata and generate the needed argTypes and controls for your stories. However, if you need additional customization, you can always [define them manually](#fully-custom-args). + ### Controls are not automatically generated for my component + If you're working with Angular, Ember, or Web Components, automatic argTypes and controls inference will not work out of the box and requires you to provide [additional configuration](#choosing-the-control-type) to allow Storybook to retrieve the necessary metadata and generate the needed argTypes and controls for your stories. However, if you need additional customization, you can always [define them manually](#fully-custom-args). ## API @@ -727,6 +488,6 @@ Default: `'none'` Specifies how the controls are sorted. -- **none**: Unsorted, displayed in the same order the arg types are processed in -- **alpha**: Sorted alphabetically, by the arg type's name -- **requiredFirst**: Same as `alpha`, with any required arg types displayed first +* **none**: Unsorted, displayed in the same order the arg types are processed in +* **alpha**: Sorted alphabetically, by the arg type's name +* **requiredFirst**: Same as `alpha`, with any required arg types displayed first diff --git a/docs/essentials/highlight.mdx b/docs/essentials/highlight.mdx index 9c498024c05b..66d56874a21e 100644 --- a/docs/essentials/highlight.mdx +++ b/docs/essentials/highlight.mdx @@ -12,24 +12,12 @@ To highlight DOM elements with the addon, you'll need to emit the `HIGHLIGHT` ev {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -We recommend choosing the most specific selector possible to avoid highlighting elements other addons use. This is because the addon tries to match selectors against the entire DOM tree. - + We recommend choosing the most specific selector possible to avoid highlighting elements other addons use. This is because the addon tries to match selectors against the entire DOM tree. ### Reset highlighted elements @@ -38,24 +26,12 @@ Out of the box, Storybook automatically removes highlighted elements when transi {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -The `emit` function derived from the `useChannel` API hook creates a communication channel in Storybook's UI to listen for events and update the UI accordingly. The Highlight addon uses this channel to listen to custom events and update the highlighted elements (if any) accordingly. - + The `emit` function derived from the `useChannel` API hook creates a communication channel in Storybook's UI to listen for events and update the UI accordingly. The Highlight addon uses this channel to listen to custom events and update the highlighted elements (if any) accordingly. ## Customize style @@ -64,17 +40,7 @@ By default, the addon applies a standard style to the highlighted elements you'v {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/essentials/index.mdx b/docs/essentials/index.mdx index fd16a19fdc69..de6be26ae655 100644 --- a/docs/essentials/index.mdx +++ b/docs/essentials/index.mdx @@ -5,14 +5,14 @@ hideRendererSelector: true A major strength of Storybook are [addons](https://storybook.js.org/addons) that extend Storybook’s UI and behavior. Storybook ships by default with a set of “essential” addons that add to the initial user experience. There are many third-party addons as well as “official” addons developed by the Storybook core team. -- [Actions](./actions.md) -- [Backgrounds](./backgrounds.md) -- [Controls](./controls.md) -- [Docs](../writing-docs/index.md) -- [Highlight](./highlight.md) -- [Measure & outline](./measure-and-outline.md) -- [Toolbars & globals](./toolbars-and-globals.md) -- [Viewport](./viewport.md) +* [Actions](./actions.md) +* [Backgrounds](./backgrounds.md) +* [Controls](./controls.md) +* [Docs](../writing-docs/index.md) +* [Highlight](./highlight.md) +* [Measure & outline](./measure-and-outline.md) +* [Toolbars & globals](./toolbars-and-globals.md) +* [Viewport](./viewport.md) ### Installation @@ -22,13 +22,7 @@ However, if you intend to install the Essentials addon manually into an existing {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -36,12 +30,7 @@ Update your Storybook configuration (in [`.storybook/main.js|ts`](../configure/i {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -53,24 +42,13 @@ If you need to reconfigure any of the [individual Essentials addons](https://sto {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -78,12 +56,7 @@ Below is an abridged configuration and table with all the available options for {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -108,17 +81,10 @@ For example, if you wanted to disable the [backgrounds addon](./backgrounds.md), {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -You can use the following keys for each individual addon: `actions`, `backgrounds`, `controls`, `docs`, `viewport`, `toolbars`, `measure`, `outline`, and `highlight`. - + You can use the following keys for each individual addon: `actions`, `backgrounds`, `controls`, `docs`, `viewport`, `toolbars`, `measure`, `outline`, and `highlight`. diff --git a/docs/essentials/interactions.mdx b/docs/essentials/interactions.mdx index e00020a48da1..64656e7b74eb 100644 --- a/docs/essentials/interactions.mdx +++ b/docs/essentials/interactions.mdx @@ -22,13 +22,7 @@ Run the following command to install the interactions addon and related dependen {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -36,19 +30,12 @@ Next, update [`.storybook/main.js|ts`](../configure/index.md#configure-story-ren {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -Make sure to list `@storybook/addon-interactions` **after** the [`@storybook/addon-essentials`](./index.md) addon (or the [`@storybook/addon-actions`](./actions.md) if you've installed it individually). - + Make sure to list `@storybook/addon-interactions` **after** the [`@storybook/addon-essentials`](./index.md) addon (or the [`@storybook/addon-actions`](./actions.md) if you've installed it individually). Now when you run Storybook, the Interactions addon will be enabled. @@ -63,17 +50,7 @@ Make sure to import the Storybook wrappers for Vitest and Testing Library via `@ {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -84,9 +61,7 @@ While you can refer to the [Testing Library documentation](https://testing-libra Any `args` that have been marked as an Action, either using the [argTypes annotation](./actions.md#action-argtype-annotation) or the [argTypesRegex](./actions.md#automatically-matching-args), will be automatically converted to a [Jest mock function](https://jestjs.io/docs/mock-function-api) (spy). This allows you to make assertions about calls to these functions. - -To mock functions in your Storybook stories for reliable and isolated component testing, use the named `fn` import from `@storybook/test`. - + To mock functions in your Storybook stories for reliable and isolated component testing, use the named `fn` import from `@storybook/test`. ## API diff --git a/docs/essentials/measure-and-outline.mdx b/docs/essentials/measure-and-outline.mdx index 883c9ac90a39..e3217135115a 100644 --- a/docs/essentials/measure-and-outline.mdx +++ b/docs/essentials/measure-and-outline.mdx @@ -17,9 +17,7 @@ With Storybook's Measure addon, you can quickly visualize each component's measu - -Alternatively you can press the `m` key on your keyboard to toggle the addon. - + Alternatively you can press the `m` key on your keyboard to toggle the addon. ## Outline addon @@ -29,7 +27,7 @@ When building your layouts, checking the visual alignment of all components can With Storybook's Outline addon, you can toggle the outlines associated with all your UI elements, allowing you to spot bugs and broken layouts instantly with a click of a button. ## API diff --git a/docs/essentials/themes.mdx b/docs/essentials/themes.mdx index 679f74123069..a90bb98a5f37 100644 --- a/docs/essentials/themes.mdx +++ b/docs/essentials/themes.mdx @@ -16,12 +16,7 @@ For libraries that expose themes to components through providers, such as [Mater {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -31,12 +26,7 @@ For libraries that rely on CSS classes on a parent element to determine the them {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -46,11 +36,6 @@ For libraries that rely on data attributes on a parent element to determine the {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/essentials/toolbars-and-globals.mdx b/docs/essentials/toolbars-and-globals.mdx index f1430d93aa0d..8591e5ab300b 100644 --- a/docs/essentials/toolbars-and-globals.mdx +++ b/docs/essentials/toolbars-and-globals.mdx @@ -20,19 +20,12 @@ Storybook has a simple, declarative syntax for configuring toolbar menus. In you {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -As globals are _global_ you can _only_ set `globalTypes` in [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering). - + As globals are *global* you can *only* set `globalTypes` in [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering). When you start your Storybook, you should see a new dropdown with the `light` and `dark` options in your toolbar. @@ -41,71 +34,44 @@ When you start your Storybook, you should see a new dropdown with the `light` an We have a `global` implemented. Let's wire it up! We can consume our new `theme` global in a decorator using the `context.globals.theme` value. - - -For example, suppose you are using [`styled-components`](https://styled-components.com/). You can add a theme provider decorator to your [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering) config: + + For example, suppose you are using [`styled-components`](https://styled-components.com/). You can add a theme provider decorator to your [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering) config: -{/* prettier-ignore-start */} - - + {/* prettier-ignore-start */} -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} - + + For example, suppose you are using [`Vuetify`](https://vuetifyjs.com/en/). You can add a theme provider decorator to your [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering) config: -For example, suppose you are using [`Vuetify`](https://vuetifyjs.com/en/). You can add a theme provider decorator to your [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering) config: + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} - - - -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} - - -For example, suppose you are using [`Angular Material`](https://material.angular.io/). You can add a theme provider decorator to your [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering) config: + + For example, suppose you are using [`Angular Material`](https://material.angular.io/). You can add a theme provider decorator to your [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering) config: -{/* prettier-ignore-start */} - - + {/* prettier-ignore-start */} -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} + Depending on your framework and theming library, you can extend your [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering) and provide a decorator to load the theme. For example: -Depending on your framework and theming library, you can extend your [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rendering) and provide a decorator to load the theme. For example: + {/* prettier-ignore-start */} -{/* prettier-ignore-start */} - - - -{/* prettier-ignore-end */} + + {/* prettier-ignore-end */} ## Advanced usage @@ -118,26 +84,17 @@ In your [`.storybook/preview.js|ts`](../configure/index.md#configure-story-rende {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -The `icon` element used in the examples loads the icons from the `@storybook/components` package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. - + The `icon` element used in the examples loads the icons from the `@storybook/components` package. See [here](../faq.md#what-icons-are-available-for-my-toolbar-or-my-addon) for the list of available icons that you can use. - -The `@storybook/addon-toolbars` addon is required to use toolbars. The toolbars addon is included by default in -`@storybook/addon-essentials`. - + The `@storybook/addon-toolbars` addon is required to use toolbars. The toolbars addon is included by default in + `@storybook/addon-essentials`. By adding the configuration element `right`, the text will be displayed on the right side in the toolbar menu once you connect it to a decorator. @@ -161,23 +118,7 @@ Using the example above, you can modify any story to retrieve the **Locale** `gl {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -189,11 +130,7 @@ Using the ThemeProvider example above, you could expand it to display which them {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -205,10 +142,6 @@ For example, if you were working on a [toolbar addon](../addons/addon-types.md#t {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} diff --git a/docs/essentials/viewport.mdx b/docs/essentials/viewport.mdx index 7fa6a18a69c7..627f3dcae1f0 100644 --- a/docs/essentials/viewport.mdx +++ b/docs/essentials/viewport.mdx @@ -7,10 +7,7 @@ title: 'Viewport' The Viewport toolbar item allows you to adjust the dimensions of the iframe your story is rendered in. It makes it easy to develop responsive UIs. ## Configuration @@ -19,12 +16,7 @@ Out of the box, the Viewport addon offers you a standard set of viewports that y {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -51,53 +43,46 @@ The Viewport addon includes a selection of devices that you can use to test your | Device | Description | Dimensions
(w×h, px) | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -| iPhone 5 | Configures the iPhone 5 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone5', }},` | 320 × 568 | -| iPhone 6 | Enables the iPhone 6 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone6', }},` | 375 × 667 | -| iPhone 6 Plus | Includes the iPhone 6 Plus as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone6p', }},` | 414 × 736 | -| iPhone 8 Plus | Sets the iPhone 8 Plus as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone8p', }},` | 414 × 736 | -| iPhone X | Configures the iPhone X as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonex', }},` | 375 × 812 | -| iPhone XR | Includes the iPhone XR as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonexr', }},` | 414 × 896 | -| iPhone XS Max | Sets the iPhone XS Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonexsmax', }},` | 414 × 896 | -| iPhone SE (2nd generation) | Configures the iPhone SE (2nd generation) as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonese2', }},` | 375 × 667 | -| iPhone 12 mini | Enables the iPhone 12 Mini to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12mini', }},` | 375 × 812 | -| iPhone 12 | Includes the iPhone 12 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12', }},` | 390 × 844 | -| iPhone 12 Pro Max | Configures the iPhone 12 Pro Max as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12promax', }},` | 428 × 926 | -| iPhone SE 3rd generation | Enables the iPhone SE (3rd generation) to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphoneSE3', }},` | 375 × 667 | -| iPhone 13 | Includes the iPhone 13 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13', }},` | 390 × 844 | -| iPhone 13 Pro | Enables the iPhone 13 Pro to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13pro', }},` | 390 × 844 | -| iPhone 13 Pro Max | Configures the iPhone 13 Pro Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13promax', }},` | 428 × 926 | -| iPhone 14 | Enables the iPhone 14 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14', }},` | 390 × 844 | -| iPhone 14 Pro | Includes the iPhone 14 Pro as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14pro', }},` | 393 × 852 | -| iPhone 14 Pro Max | Sets the iPhone 14 Pro Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14promax', }},` | 430 × 932 | -| Galaxy S5 | Configures the Galaxy S5 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'galaxys5', }},` | 360 × 640 | -| Galaxy S9 | Enables the Galaxy S9 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'galaxys9', }},` | 360 × 740 | -| Nexus 5X | Includes the Nexus 5x as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'nexus5x', }},` | 412 × 668 | -| Nexus 6P | Sets the Nexus 6P as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'nexus6p', }},` | 412 × 732 | -| Pixel | Configures the Pixel as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'pixel', }},` | 540 × 960 | -| Pixel XL | Enables the Pixel XL to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'pixelxl', }},` | 720 × 1280 | -| Small mobile | Enabled by default.
Configures a small form factor generic mobile device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'mobile1', }},` | 320 × 568 | -| Large mobile | Enabled by default.
Configures a large form factor mobile device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'mobile2', }},` | 414 × 896 | -| iPad | Includes the iPad as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad', }},` | 768 × 1024 | -| iPad Pro 10.5-in | Enables the iPad Pro (10.5-inch) to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad10p', }},` | 834 × 112 | -| iPad Pro 11-in | Configures the iPad Pro (11-inch) as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad11p', }},` | 834 × 1194 | -| iPad Pro 12.9-in | Sets the iPad Pro (12.9-inch) as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad12p', }},` | 1024 × 1366 | -| Tablet | Enabled by default.
Configures a standard form factor tablet device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'tablet', }},` | 834 × 1112 | +| iPhone 5 | Configures the iPhone 5 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone5', }},` | 320 × 568 | +| iPhone 6 | Enables the iPhone 6 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone6', }},` | 375 × 667 | +| iPhone 6 Plus | Includes the iPhone 6 Plus as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone6p', }},` | 414 × 736 | +| iPhone 8 Plus | Sets the iPhone 8 Plus as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone8p', }},` | 414 × 736 | +| iPhone X | Configures the iPhone X as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonex', }},` | 375 × 812 | +| iPhone XR | Includes the iPhone XR as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonexr', }},` | 414 × 896 | +| iPhone XS Max | Sets the iPhone XS Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonexsmax', }},` | 414 × 896 | +| iPhone SE (2nd generation) | Configures the iPhone SE (2nd generation) as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphonese2', }},` | 375 × 667 | +| iPhone 12 mini | Enables the iPhone 12 Mini to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12mini', }},` | 375 × 812 | +| iPhone 12 | Includes the iPhone 12 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12', }},` | 390 × 844 | +| iPhone 12 Pro Max | Configures the iPhone 12 Pro Max as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone12promax', }},` | 428 × 926 | +| iPhone SE 3rd generation | Enables the iPhone SE (3rd generation) to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphoneSE3', }},` | 375 × 667 | +| iPhone 13 | Includes the iPhone 13 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13', }},` | 390 × 844 | +| iPhone 13 Pro | Enables the iPhone 13 Pro to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13pro', }},` | 390 × 844 | +| iPhone 13 Pro Max | Configures the iPhone 13 Pro Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone13promax', }},` | 428 × 926 | +| iPhone 14 | Enables the iPhone 14 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14', }},` | 390 × 844 | +| iPhone 14 Pro | Includes the iPhone 14 Pro as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14pro', }},` | 393 × 852 | +| iPhone 14 Pro Max | Sets the iPhone 14 Pro Max as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'iphone14promax', }},` | 430 × 932 | +| Galaxy S5 | Configures the Galaxy S5 as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'galaxys5', }},` | 360 × 640 | +| Galaxy S9 | Enables the Galaxy S9 to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'galaxys9', }},` | 360 × 740 | +| Nexus 5X | Includes the Nexus 5x as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'nexus5x', }},` | 412 × 668 | +| Nexus 6P | Sets the Nexus 6P as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'nexus6p', }},` | 412 × 732 | +| Pixel | Configures the Pixel as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'pixel', }},` | 540 × 960 | +| Pixel XL | Enables the Pixel XL to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'pixelxl', }},` | 720 × 1280 | +| Small mobile | Enabled by default.
Configures a small form factor generic mobile device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'mobile1', }},` | 320 × 568 | +| Large mobile | Enabled by default.
Configures a large form factor mobile device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'mobile2', }},` | 414 × 896 | +| iPad | Includes the iPad as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad', }},` | 768 × 1024 | +| iPad Pro 10.5-in | Enables the iPad Pro (10.5-inch) to be used with the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad10p', }},` | 834 × 112 | +| iPad Pro 11-in | Configures the iPad Pro (11-inch) as a device for the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad11p', }},` | 834 × 1194 | +| iPad Pro 12.9-in | Sets the iPad Pro (12.9-inch) as a device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'ipad12p', }},` | 1024 × 1366 | +| Tablet | Enabled by default.
Configures a standard form factor tablet device to be used by the Viewport addon.
`parameters: { viewport: { defaultViewport: 'tablet', }},` | 834 × 1112 | {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} - -The generic devices are enabled by default as they are the most common for testing responsive UIs. You don't need to include them in your configuration if you want to use them. For the implementation details, see the [source code](https://github.com/storybookjs/storybook/tree/next/code/addons/viewport) for the Viewport addon. - + The generic devices are enabled by default as they are the most common for testing responsive UIs. You don't need to include them in your configuration if you want to use them. For the implementation details, see the [source code](https://github.com/storybookjs/storybook/tree/next/code/addons/viewport) for the Viewport addon. ### Add new devices @@ -106,11 +91,7 @@ If you have either a specific viewport or a list of viewports that you need to u {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -118,12 +99,7 @@ Make the following changes to use them in your Storybook: {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -135,12 +111,7 @@ For instance, if you want to use these two with the minimal set of viewports, yo {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -154,31 +125,15 @@ Update your story through [parameters](../writing-stories/parameters.md) to incl {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} ### Keyboard shortcuts -- Previous viewport: alt + shift + v -- Next viewport: alt + v -- Reset viewport: alt + control + v +* Previous viewport: alt + shift + v +* Next viewport: alt + v +* Reset viewport: alt + control + v If you need, you can edit them on the shortcuts page. @@ -248,6 +203,6 @@ A minimal set of viewports provided by the Viewport addon, listed below: | Device | Description | Dimensions
(w×h, px) | | ------------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -| Small mobile | A small mobile device size
`parameters: { viewport: { defaultViewport: 'mobile1', }},` | 320 × 568 | -| Large mobile | A large mobile device size
`parameters: { viewport: { defaultViewport: 'mobile2', }},` | 414 × 896 | -| Tablet | A tablet device size
`parameters: { viewport: { defaultViewport: 'tablet', }},` | 834 × 1112 | +| Small mobile | A small mobile device size
`parameters: { viewport: { defaultViewport: 'mobile1', }},` | 320 × 568 | +| Large mobile | A large mobile device size
`parameters: { viewport: { defaultViewport: 'mobile2', }},` | 414 × 896 | +| Tablet | A tablet device size
`parameters: { viewport: { defaultViewport: 'tablet', }},` | 834 × 1112 | diff --git a/docs/faq.mdx b/docs/faq.mdx index cee3ae1e941a..fd75be13a599 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -61,9 +61,7 @@ npm test -- --coverage --collectCoverageFrom='["src/**/*.{js,jsx}","!src/**/stor ``` - -If you're using [`Yarn`](https://yarnpkg.com/) as a package manager, you'll need to adjust the command accordingly. - + If you're using [`Yarn`](https://yarnpkg.com/) as a package manager, you'll need to adjust the command accordingly. ## How do I setup Storybook to share Webpack configuration with Next.js? @@ -94,12 +92,7 @@ To fix this, you can wrap the package name inside your Storybook configuration f {/* prettier-ignore-start */} - + {/* prettier-ignore-end */} @@ -124,15 +117,15 @@ export default { A common error is that an addon tries to access the "channel", but the channel is not set. It can happen in a few different cases: -1. You're trying to access addon channel (e.g., by calling `setOptions`) in a non-browser environment like Jest. You may need to add a channel mock: +1. You're trying to access addon channel (e.g., by calling `setOptions`) in a non-browser environment like Jest. You may need to add a channel mock: - ```js - import { addons, mockChannel } from '@storybook/preview-api'; + ```js + import { addons, mockChannel } from '@storybook/preview-api'; - addons.setChannel(mockChannel()); - ``` + addons.setChannel(mockChannel()); + ``` -2. In React Native, it's a special case documented in [#1192](https://github.com/storybookjs/storybook/issues/1192) +2. In React Native, it's a special case documented in [#1192](https://github.com/storybookjs/storybook/issues/1192) ## Why aren't Controls visible in the Canvas panel but visible in Docs? @@ -303,9 +296,7 @@ We're only covering versions 5.3 and 5.0 as they were important milestones for S | | CLI options | [See current documentation](./api/cli-options.md) | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.3/docs/src/pages/configurations/cli-options) | [See versioned documentation](https://github.com/storybookjs/storybook/tree/release/5.0/docs/src/pages/configurations/cli-options) | - -If you have stories written with the older `storiesOf` format, it was removed in Storybook 8.0 and is no longer maintained. We recommend that you migrate your stories to CSF. See the [migration guide](./migration-guide.md#storiesof-to-csf) for more information. However, if you need, you can still access the old `storiesOf` [documentation](https://github.com/storybookjs/storybook/blob/release/5.3/docs/src/pages/formats/storiesof-api/index.md) for reference. - + If you have stories written with the older `storiesOf` format, it was removed in Storybook 8.0 and is no longer maintained. We recommend that you migrate your stories to CSF. See the [migration guide](./migration-guide.md#storiesof-to-csf) for more information. However, if you need, you can still access the old `storiesOf` [documentation](https://github.com/storybookjs/storybook/blob/release/5.3/docs/src/pages/formats/storiesof-api/index.md) for reference. ## What icons are available for my toolbar or my addon? @@ -313,7 +304,7 @@ If you have stories written with the older `storiesOf` format, it was removed in With the [`@storybook/components`](https://www.npmjs.com/package/@storybook/components) package, you get a set of icons that you can use to customize your UI. Use the table below as a reference while writing your addon or defining your Storybook global types. Go through this [story](https://main--5a375b97f4b14f0020b0cda3.chromatic.com/?path=/story/basics-icon--labels) to see how the icons look. - + + ``` + {/* prettier-ignore-end */} -
+
- + +