preview.js|jsx|ts|tsx configuration file purpose
The preview.js|jsx|ts|tsx configuration file controls the way stories are rendered. You can also use it to run code that applies to all stories.
Storybook · API · all subjects
configuration
142 notes in this subject, read out of this brain and free to use. This is page 1 of 3.
main.js|ts configuration file purpose
The main.js|ts file is 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.
manager.js|ts configuration file purpose
The manager.js|ts configuration file controls the behavior of Storybook's UI, the manager.
Parameters purpose
Parameters are static metadata used to configure your stories and addons in Storybook. They are specified at the story, meta (component), and project (global) levels.
main.js/ts configuration documentation
The main configuration file for Storybook is named main.js or main.ts. This configuration controls core Storybook settings and behavior.
main.js addons field type and purpose
The addons field in main.js|ts configuration registers the addons loaded by Storybook. It has type (string | { name: string; options?: AddonOptions })[] meaning it accepts an array of strings or objects, where objects have a required name field and an optional options field of type AddonOptions.
addons field addon configuration
Each addon in the addons array can be registered either as a simple string (the addon name) or as an object with a name field (required, type string) and an options field (optional, type AddonOptions). Refer to each addon's documentation for its available options.
babelDefault vs babel configuration
To adjust Storybook's Babel setup directly (not via an addon), use the babel main config field instead of babelDefault. babelDefault is intended for addon authors.
babelDefault main config field
The babelDefault field in main.js|ts allows customization of Storybook's Babel setup. It accepts a function with type (config: Babel.Config, options: Options) => Babel.Config | Promise<Babel.Config>. It is applied to the preview config before any user presets have been applied, making it useful for addon authors so that the end user's babel setup can override it.
babelDefault for addon authors
Addon authors should use babelDefault instead of babel. The babelDefault preset is applied to the preview config before any user presets have been applied.
babel configuration requires @storybook/addon-webpack5-compiler-babel addon
The options provided by Babel are only applicable if the @storybook/addon-webpack5-compiler-babel addon is enabled.
babel main.js configuration function signature
The babel field in main.js|ts configuration has type (config: Babel.Config, options: Options) => Babel.Config | Promise<Babel.Config>. It customizes Storybook's Babel setup.
Babel configuration files are automatically detected
If an existing Babel configuration file exists (such as .babelrc), it will be automatically detected and used by Storybook without any additional configuration required.
babel Options type definition
The Options type for babel configuration is { configType?: 'DEVELOPMENT' | 'PRODUCTION' }. There are other options that are difficult to document; introspecting the type definition is recommended for more information.
build.test.disabledAddons option
The disabledAddons string array option sets the list of addons that will be disabled in the build output.
build.test.disableTreeShaking option
The disableTreeShaking boolean option disables tree shaking in the build.
build.test options are automatically enabled with --test flag
The options in the build.test configuration are automatically enabled when the --test flag is provided to the storybook build command. Users should only override these options if they need to disable a specific feature for their project or if they are debugging a build issue.
build.test.disableMDXEntries option
The disableMDXEntries boolean option, when enabled, removes user-written documentation entries in MDX format from the build.
build.test.disableSourcemaps option
The disableSourcemaps boolean option overrides the default behavior of generating source maps for the build.
build.test.disableBlocks option
The disableBlocks boolean option excludes the @storybook/addon-docs/blocks module from the build, which is responsible for generating automatic documentation with Docs Blocks.
build.test configuration field
The build.test field accepts a TestBuildFlags type and configures Storybook's production builds for performance testing purposes by disabling certain features from the build. This feature is enabled by setting the --test flag when running the storybook build command.
build.test.disableAutoDocs option
The disableAutoDocs boolean option prevents automatic documentation generated with the autodocs feature from being included in the build.
build.test field structure and options
The build.test field has the following optional properties: disableBlocks (boolean), disabledAddons (string[]), disableMDXEntries (boolean), disableAutoDocs (boolean), disableDocgen (boolean), disableSourcemaps (boolean), disableTreeShaking (boolean). All are optional boolean or array properties.
build configuration key in main.js/ts
The build key in main.js/ts configuration accepts a TestBuildConfig type and provides configuration options to optimize Storybook's production build output.
build.test.disableDocgen option
The disableDocgen boolean option disables automatic argType and component property inference with any of the supported static analysis tools based on the framework being used.
docs.defaultName property
The defaultName property is a string that sets the name used for generated documentation pages. It is optional and defaults to 'Docs'.
docs configuration object type
The docs configuration object in main.js/ts has the following structure: { defaultName?: string; docsMode?: boolean }
docs configuration configures auto-generated documentation
The docs configuration in main.js/ts configures Storybook's auto-generated documentation feature.
docs.docsMode property
The docsMode property is a boolean that, when enabled, shows only documentation pages in the sidebar. It is usually set with the --docs CLI flag.
allowedHosts configuration
The allowedHosts property in core configuration is of type string[] | true with a default value of []. It configures the allowed hosts for the Storybook dev server, used for Origin and Host header validation. Storybook's localhost and local network addresses are always allowed. Use this when accessing your local Storybook instance through a reverse proxy such as a webapp dev server. Set to true to disable hostname validation (insecure).
core configuration object structure
The core configuration object in main.js|ts configures Storybook's internal features with the following optional properties: allowedHosts (string[] | true), builder (string | { name: string; options?: BuilderOptions }), channelOptions (ChannelOptions), crossOriginIsolated (boolean), disableProjectJson (boolean), disableTelemetry (boolean), disableWebpackDefaults (boolean), disableWhatsNewNotifications (boolean), enableCrashReports (boolean), and renderer (RendererName).
enableCrashReports configuration
The enableCrashReports property in core configuration is of type boolean. When enabled, it allows crash reports to be sent to Storybook telemetry.
disableProjectJson configuration
The disableProjectJson property in core configuration is of type boolean. When enabled, it disables the generation of project.json, which is a file containing Storybook metadata.
renderer configuration
The renderer property in core configuration is of type RendererName. It is an undocumented field whose usage and purpose are unclear based on available documentation.
disableWhatsNewNotifications configuration
The disableWhatsNewNotifications property in core configuration is of type boolean. When enabled, it disables the "What's New" notifications in the UI for new Storybook versions and ecosystem updates such as addons and content.
disableWebpackDefaults configuration
The disableWebpackDefaults property in core configuration is of type boolean. When enabled, it disables Storybook's default Webpack configuration.
disableTelemetry configuration
The disableTelemetry property in core configuration is of type boolean. When enabled, it disables Storybook's telemetry collection.
crossOriginIsolated configuration
The crossOriginIsolated property in core configuration is of type boolean. It enables CORS headers to run the document in a secure context, as required by SharedArrayBuffer security requirements. When enabled in development mode, it adds the headers: Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp.
channelOptions.maxDepth
The maxDepth property in channelOptions is of type number with a default value of 3. It sets the maximum depth of nested objects to serialize across the channel. Larger values will be slower.
channelOptions configuration
The channelOptions property in core configuration is of type ChannelOptions with properties: allowDate (boolean), allowRegExp (boolean), allowSymbol (boolean), allowUndefined (boolean), maxDepth (number), and space (number | undefined). It configures the channel used by Storybook to communicate between the manager and preview. Only maxDepth is likely to be used by most developers.
builder configuration
The builder property in core configuration is of type '@storybook/builder-vite' | '@storybook/builder-webpack5' | { name: '@storybook/builder-vite' | '@storybook/builder-webpack5'; options?: BuilderOptions }. It configures Storybook's builder, either Vite or Webpack. Note that with the new Framework API, framework.options.builder is now the preferred way to configure the builder, and core.builder.options should only be used if you need to configure a builder that is not part of a framework.
env field type signature
The type signature for the env configuration field is: (config: { [key: string]: string }) => { [key: string]: string }
env configuration field
The env field is a main.js/ts configuration option that accepts a function. The function takes a config object with string keys mapping to string values, and returns an object with the same structure: { [key: string]: string }. This field defines custom Storybook environment variables.
framework.options.builder field
The options.builder field has type Record<string, any>. It configures Storybook's builder, which can be either Vite or Webpack.
framework.options field
The options field within the framework configuration has type Record<string, any>. It is optional. Many options are framework-specific, but some are shared across frameworks, such as those that configure Storybook's builder.
framework configuration purpose
The framework configuration field configures Storybook based on a set of framework-specific settings.
framework configuration field type
The framework field in main.js/ts configuration has type FrameworkName | { name: FrameworkName; options?: FrameworkOptions }. It is a required field.
framework.name field
The name field within the framework configuration has type string. It specifies which framework to use. Available frameworks and their specific options can be found in the framework documentation.
features main.js configuration object
The features field in main.js|ts configuration accepts an object that enables or disables Storybook features. Available fields depend on renderer. Common fields across all renderers: actions (boolean, default true), argTypeTargetsV7 (boolean, default true), babelRemoveBugfixes (boolean, webpack only), backgrounds (boolean, default true), changeDetection (boolean, default true), controls (boolean, default true), developmentModeForBuild (boolean), highlight (boolean, default true), interactions (boolean, default true), legacyDecoratorFileOrder (boolean), measure (boolean, default true), outline (boolean, default true), sidebarOnboardingChecklist (boolean, default true), menuOnboardingChecklist (boolean, default true), toolbars (boolean), viewport (boolean, default true). React-specific fields: componentsManifest (boolean, default false), experimentalCodeExamples (boolean), experimentalDocgenServer (boolean, default false), experimentalReview (boolean, default false), experimentalTestSyntax (boolean). Angular-specific field: angularFilterNonInputControls (boolean).
argTypeTargetsV7 feature
The argTypeTargetsV7 feature is experimental and can be configured in main.js features. Type: boolean. Default: true. It filters args with a 'target' on the type from the render function.
experimentalCodeExamples feature React only
The experimentalCodeExamples feature is experimental and React-specific. Type: boolean. It enables the new code example generation method for React components as seen in story previews in autodocs pages. Unlike the current implementation, this method reads the actual stories source file, which is faster to generate, more readable, and more accurate. However, snippets are not dynamic and won't update if you change values in the Controls table. This flag is superseded by experimentalDocgenServer which provides the same static snippet behavior along with faster, more accurate docgen.
developmentModeForBuild feature
The developmentModeForBuild feature can be configured in main.js features. Type: boolean. It sets NODE_ENV to 'development' in built Storybooks for better testing and debugging capabilities.
controls feature
The controls feature can be enabled or disabled in main.js features configuration. Type: boolean. Default: true. Enables the Controls feature.
componentsManifest feature React only
The componentsManifest feature is React-specific and can be configured in main.js features. Type: boolean. Default: false. It generates manifests used by the MCP server. When combined with experimentalDocgenServer, manifests use a ref-based format with per-component JSON snapshots for faster MCP loading.
changeDetection feature
The changeDetection feature can be enabled or disabled in main.js features configuration. Type: boolean. Default: true. When enabled, Storybook monitors your git working tree and the builder's module graph to show which stories are new, modified, or related to code changes. Changed stories are displayed with status icons in the sidebar.
backgrounds feature
The backgrounds feature can be enabled or disabled in main.js features configuration. Type: boolean. Default: true. Enables the Backgrounds feature.
babelRemoveBugfixes feature
The babelRemoveBugfixes feature is webpack builder only. Type: boolean. It disables the bugfixes option in @babel/preset-env for Webpack builder. This option was removed in Babel 8 and now causes Babel to throw an error. Set this to true if you use Babel 8 and Storybook fails to detect your Babel version.
experimentalDocgenServer feature React only
The experimentalDocgenServer feature is experimental and React-specific. Type: boolean. Default: false. It enables server-side docgen for React projects. Storybook extracts component metadata on the dev server using the TypeScript Language Service (via React Component Meta) instead of injecting docgen into the preview bundle. This provides faster startup, more accurate Controls and ArgTypes tables in autodocs, and improved static code snippets in docs and the Code panel. Manifests and the MCP server use an optimized ref-based format that loads faster for AI agents. When enabled, you do not need experimentalCodeExamples because snippet generation is handled by the server-side story-docs service. Snippets are static and won't update if you change values in the Controls table. This feature is currently only supported for React projects.
actions feature
The actions feature can be enabled or disabled in main.js features configuration. Type: boolean. Default: true. Enables the Actions feature.
experimentalReview feature React only
The experimentalReview feature is experimental and React-specific. Type: boolean. Default: false. It enables the experimental agentic review feature, which allows you to review the work an AI agent has done in your Storybook. This feature builds on changeDetection, which must also be enabled (it is enabled by default).