mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-06 07:21:16 +08:00
122 lines
9.1 KiB
Plaintext
122 lines
9.1 KiB
Plaintext
---
|
||
title: 'Configure Storybook'
|
||
sidebar:
|
||
order: 8
|
||
title: Configure
|
||
---
|
||
|
||
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.mdx).
|
||
</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](./integration/typescript.mdx). Listed below are the available options and examples of how to use them.
|
||
|
||
{/* prettier-ignore-start */}
|
||
|
||
<CodeSnippets path="main-config-typical.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
<Callout variant="info">
|
||
This configuration file is a [preset](../addons/addon-types.mdx) and, as such, has a powerful interface, which can be further customized. Read our documentation on writing [presets](../addons/writing-presets.mdx) 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](./integration/images-and-assets.mdx#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](./integration/typescript.mdx) <br /> `typescript: { check: false, checkOptions: {} }` |
|
||
| `framework` | Configures Storybook based on a set of [framework-specific](./integration/frameworks.mdx) settings <br /> `framework: { name: '@storybook/svelte-vite', options:{} }` |
|
||
| `core` | Configures Storybook's [internal features](../api/main-config/main-config-core.mdx) <br /> `core: { disableTelemetry: true, }` |
|
||
| `docs` | Configures Storybook's [auto-generated documentation](../writing-docs/autodocs.mdx)<br /> `docs: { autodocs: 'tag' }` |
|
||
| `features` | Enables Storybook's [additional features](../api/main-config/main-config-features.mdx)<br /> See table below for a list of available features |
|
||
| `refs` | Configures [Storybook composition](../sharing/storybook-composition.mdx) <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.mdx) 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.mdx#using-storybook-configuration). <br /> `env: (config) => ({...config, EXAMPLE_VAR: 'Example var' }),` |
|
||
| `build` | Optimizes Storybook's production [build](../api/main-config/main-config-build.mdx) for performance by excluding specific features from the bundle. Useful when decreased build times are a priority. <br /> `build: { test: {} }` |
|
||
|
||
## 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 path="storybook-main-js-md-files.md" />
|
||
|
||
{/* 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 path="main-config-stories-with-object.md" />
|
||
|
||
{/* 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 path="storybook-storyloading-with-directory.md" />
|
||
|
||
{/* 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 path="main-config-stories-with-logic.md" />
|
||
|
||
{/* prettier-ignore-end */}
|
||
|
||
#### Known limitations
|
||
|
||
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.mdx) from version 1 to version 3 are supported.
|
||
* 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.mdx#global-decorators) and [parameters](../writing-stories/parameters.mdx#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.mdx#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.mdx#global-decorators)
|
||
* `parameters` - an object of global [parameters](../writing-stories/parameters.mdx#global-parameters)
|
||
* `globalTypes` - definition of [globalTypes](../essentials/toolbars-and-globals.mdx#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.mdx#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](./user-interface/features-and-behavior.mdx) and to configure Storybook’s [theme](./user-interface/theming.mdx).
|