mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-08 11:11:53 +08:00
975ad7604b
- Rename `introduction.md`, `overview.md`, `how-to-contribute.md` pages -> `index.md` pages - Add all-new `index.md` pages for Sharing and API - Find/replace `introduction.md`/`overview.md` -> `index.md` - Find/replace `/introduction`/`/overview` -> `/` - Add `hideRendererSelector: true` to frontmatter of (some) pages that aren't conditional on renderer
173 lines
11 KiB
Markdown
173 lines
11 KiB
Markdown
---
|
||
title: 'Configure Storybook'
|
||
---
|
||
|
||
Storybook is configured via a folder called `.storybook`, which contains various configuration files.
|
||
|
||
<Callout variant="info">
|
||
|
||
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).
|
||
|
||
</Callout>
|
||
|
||
## Configure your Storybook project
|
||
|
||
Storybook's main configuration (i.e., the `main.js|ts`) defines your Storybook project's behavior, including the location of your stories, the addons you use, feature flags and other project-specific settings. This file should be in the `.storybook` folder in your project's root directory. You can author this file in either JavaScript or [TypeScript](./typescript.md). Listed below are the available options and examples of how to use them.
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/main-config-typical.js.mdx',
|
||
'common/main-config-typical.ts.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
<Callout variant="info">
|
||
|
||
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.
|
||
|
||
</Callout>
|
||
|
||
| 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 <br/> `staticDirs: ['../public']` |
|
||
| `addons` | Sets the list of [addons](https://storybook.js.org/integrations) loaded by Storybook <br/> `addons: ['@storybook/addon-essentials']` |
|
||
| `typescript` | Configures how Storybook handles [TypeScript files](./typescript.md) <br/> `typescript: { check: false, checkOptions: {} }` |
|
||
| `framework` | Configures Storybook based on a set of [framework-specific](./frameworks.md) settings <br/> `framework: { name: '@storybook/svelte-vite', options:{} }` |
|
||
| `core` | Configures Storybook's [internal features](../api/main-config-core.md) <br/> `core: { disableTelemetry: true, }` |
|
||
| `docs` | Configures Storybook's [auto-generated documentation](../writing-docs/autodocs.md)<br/> `docs: { autodocs: 'tag' }` |
|
||
| `features` | Enables Storybook's [additional features](../api/main-config-features.md)<br/> See table below for a list of available features `features: { storyStoreV7: true }` |
|
||
| `refs` | Configures [Storybook composition](../sharing/storybook-composition.md) <br/> `refs:{ example: { title: 'ExampleStorybook', url:'https://your-url.com' } }` |
|
||
| `logLevel` | Configures Storybook's logs in the browser terminal. Useful for debugging <br/> `logLevel: 'debug'` |
|
||
| `webpackFinal` | Customize Storybook's [Webpack](../builders/webpack.md) setup <br/> `webpackFinal: async (config:any) => { return config; }` |
|
||
| `viteFinal` | Customize Storybook's Vite setup when using the [vite builder](https://github.com/storybookjs/builder-vite) <br/> `viteFinal: async (config: Vite.InlineConfig, options: Options) => { return config; }` |
|
||
| `env` | Defines custom Storybook [environment variables](./environment-variables.md#using-storybook-configuration). <br/> `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. <br/> `build: { test: {} }` |
|
||
|
||
### Feature flags
|
||
|
||
Additionally, you can also provide additional feature flags to your Storybook configuration. Below is an abridged list of available features that are currently available.
|
||
|
||
| Configuration element | Description |
|
||
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `storyStoreV7` | Configures Storybook to load stories [on demand](#on-demand-story-loading), rather than during boot up (defaults to `true` as of `v7.0`) <br/> `features: { storyStoreV7: true }` |
|
||
| `buildStoriesJson` | Generates `index.json` and `stories.json` files to help story loading with the on-demand mode (defaults to `true` when `storyStoreV7` is `true`) <br/> `features: { buildStoriesJson: true }` |
|
||
| `legacyMdx1` | Enables support for MDX version 1 as a fallback. Requires [`@storybook/mdx1-csf`](https://github.com/storybookjs/mdx1-csf) <br/> `features: { legacyMdx1: true }` |
|
||
|
||
## Configure story loading
|
||
|
||
By default, Storybook will load stories from your project based on a glob (pattern matching string) in `.storybook/main.js|ts` that matches all files in your project with extension `.stories.*`. The intention is for you to colocate a story file along with the component it documents.
|
||
|
||
```
|
||
•
|
||
└── components
|
||
├── Button.js
|
||
└── Button.stories.js
|
||
```
|
||
|
||
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).
|
||
|
||
For example, if you wanted to pull both `.md` and `.js` files from the `my-project/src/components` directory, you could write:
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/storybook-main-js-md-files.js.mdx',
|
||
'common/storybook-main-js-md-files.ts.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
### With a configuration object
|
||
|
||
Additionally, you can customize your Storybook configuration to load your stories based on a configuration object. For example, if you wanted to load your stories from a `packages/components` directory, you could adjust your `stories` configuration field into the following:
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/main-config-stories-with-object.js.mdx',
|
||
'common/main-config-stories-with-object.ts.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
When Storybook starts, it will look for any file containing the `stories` extension inside the `packages/components` directory and generate the titles for your stories.
|
||
|
||
### With a directory
|
||
|
||
You can also simplify your Storybook configuration and load the stories using a directory. For example, if you want to load all the stories inside a `packages/MyStories`, you can adjust the configuration as such:
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/storybook-storyloading-with-directory.js.mdx',
|
||
'common/storybook-storyloading-with-directory.ts.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
### With a custom implementation
|
||
|
||
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 -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/main-config-stories-with-logic.js.mdx',
|
||
'common/main-config-stories-with-logic.ts.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
### On-demand story loading
|
||
|
||
As your Storybook grows, it gets challenging to load all of your stories performantly, slowing down the loading times and yielding a large bundle. Out of the box, Storybook loads your stories on demand rather than during boot-up to improve the performance of your Storybook. If you need to load all of your stories during boot-up, you can disable this feature by setting the `storyStoreV7` feature flag to `false` in your configuration as follows:
|
||
|
||
<!-- prettier-ignore-start -->
|
||
|
||
<CodeSnippets
|
||
paths={[
|
||
'common/main-config-features-story-store-v7.js.mdx',
|
||
'common/main-config-features-story-store-v7.ts.mdx',
|
||
]}
|
||
/>
|
||
|
||
<!-- prettier-ignore-end -->
|
||
|
||
#### Known limitations
|
||
|
||
Because of the way stories are currently indexed in Storybook, loading stories on demand with `storyStoreV7` has a couple of minor limitations at the moment:
|
||
|
||
- [CSF formats](../api/csf.md) from version 1 to version 3 are supported. The `storiesOf` construct is not.
|
||
- Custom`storySort` functions are allowed based on a restricted API.
|
||
|
||
## Configure story rendering
|
||
|
||
To control the way stories are rendered and add global [decorators](../writing-stories/decorators.md#global-decorators) and [parameters](../writing-stories/parameters.md#global-parameters), create a `.storybook/preview.js` file. This is loaded in the Canvas UI, the “preview” iframe that renders your components in isolation. Use `preview.js` for global code (such as [CSS imports](../get-started/setup.md#render-component-styles) or JavaScript mocks) that applies to all stories.
|
||
|
||
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)
|
||
|
||
If you’re looking to change how to order your stories, read about [sorting stories](../writing-stories/naming-components-and-hierarchy.md#sorting-stories).
|
||
|
||
## Configure Storybook’s UI
|
||
|
||
To control the behavior of Storybook’s UI (the **“manager”**), you can create a `.storybook/manager.js` file.
|
||
|
||
This file does not have a specific API but is the place to set [UI options](./features-and-behavior.md) and to configure Storybook’s [theme](./theming.md).
|