OpenWikistorybookjs/storybook

Configure Overview

Purpose and Scope

Storybook configuration is the project-level contract between your application, the Storybook runtime, and the packages that extend it. A Storybook project is normally configured from a .storybook folder, with the main configuration file defining where stories are found, which framework package renders them, which addons participate, and which project-specific options are enabled. This page focuses on the configuration surfaces visible in the supplied source snippets: the main config, addon option objects, framework-specific cleanup, addon presets, and manager-side APIs for communicating with the running Storybook.

Sources: docs/_snippets/main-config-addons.md

A useful way to read Storybook configuration is to separate build-time decisions from runtime behavior. Build-time decisions include framework selection, story globs, builder integration, stylesheet handling, and preset-provided entries. Runtime behavior includes addon manager UI actions, query parameters, and story args that can be updated while a user is interacting with the interface. The source snippets show both halves: .storybook/main.js or .storybook/main.ts shapes the project before Storybook starts, while manager APIs such as args updates and notifications affect the active UI session.

Sources: docs/_snippets/args-usage-with-addons.md, docs/_snippets/storybook-addons-api-addnotification.md, docs/_snippets/storybook-addons-api-disablequeryparams.md

Relevant Source Files

  • docs/_snippets/args-usage-with-addons.md — Shows a manager-side addon using useArgs to read current args, update selected args, reset named args, or reset all args.
  • docs/_snippets/main-config-addons.md — Shows the main Storybook configuration in JavaScript, TypeScript, and CSF Next forms, including framework, stories, and addons.
  • docs/_snippets/nextjs-remove-addons.md — Shows how a Next.js or Next.js Vite configuration can remove older Next-specific addon entries from the addons array.
  • docs/_snippets/storybook-addon-load-external-addons-preset.md — Shows a preset exporting managerEntries and previewAnnotations so one addon or preset can load another addon’s manager and preview code.
  • docs/_snippets/storybook-addons-api-addnotification.md — Shows an addon registered with the manager API adding timed notifications, including a plain notification and one with an icon.
  • docs/_snippets/storybook-addons-api-disablequeryparams.md — Shows an addon clearing a query parameter by setting that parameter to null through the manager API.

Core Configuration Surfaces

The main config snippet is the clearest starting point because it demonstrates the primary shape every Storybook maintainer eventually edits. The framework field names the framework integration package, with comments pointing readers to examples such as React Vite, Next.js, and Vue 3 Vite. The stories field uses glob patterns for MDX files and component story files, making it the source of truth for what appears in the sidebar and what Storybook can render. The addons array then layers documentation, styling, testing, or project-specific behavior on top of that base project definition.

Sources: docs/_snippets/main-config-addons.md

The same main configuration can be authored in JavaScript or TypeScript. In the TypeScript form, the snippet imports StorybookConfig from the selected framework package, which gives the editor and compiler a framework-aware view of the available options. The experimental CSF Next examples use defineMain from the framework package’s node entry point instead of exporting a plain object directly. The important practical point is that the configuration object remains recognizable across these forms: choose a framework, point to stories, and register addons with optional configuration.

Sources: docs/_snippets/main-config-addons.md

Addon entries can be simple package names or structured objects with a package name and options. The styling example registers documentation support and then configures a styling addon with rules for CSS handling. The options include loader configuration and resolve the PostCSS implementation through Node module resolution. That example shows why addon configuration belongs in the main config rather than in an individual story: it changes how Storybook prepares the preview environment for a whole project, not how one component state is displayed.

Sources: docs/_snippets/main-config-addons.md

Addon Configuration and Preset Flow

Storybook addons can reduce repeated user configuration by shipping presets. A preset runs in the Node side of Storybook setup and can contribute entries to both the manager and preview. The external addon preset snippet appends a manager entry for another addon’s manager code and a preview annotation for that addon’s preview code. This pattern is useful when a package wants to bundle or delegate behavior without asking every consuming project to list multiple low-level entries by hand.

Sources: docs/_snippets/storybook-addon-load-external-addons-preset.md

The distinction between manager and preview matters when diagnosing configuration problems. The manager is the Storybook application shell: sidebar, toolbar, panels, notifications, and addon UI. The preview is where stories render, usually inside the preview iframe. A preset that contributes managerEntries affects the user interface around stories, while previewAnnotations affects the rendering environment used by stories themselves. When an addon appears in the UI but has no effect on rendered components, or vice versa, checking which entry type is configured is often the fastest first step.

Sources: docs/_snippets/storybook-addon-load-external-addons-preset.md

Framework Migration and Addon Lists

The Next.js removal snippet illustrates another configuration principle: the selected framework package can make older standalone addons unnecessary. Its examples show JavaScript, TypeScript, and CSF Next configurations where storybook-addon-next and storybook-addon-next-router are commented as removable entries. That does not mean every addon should be removed during a framework migration. It means the addon list should be reviewed for behavior now provided by the framework integration itself, especially when moving to nextjs or nextjs-vite style framework packages.

Sources: docs/_snippets/nextjs-remove-addons.md

Treat the addons array as an ordered inventory of project capabilities. Some entries are global utilities, such as docs generation. Others are compatibility or styling bridges. Still others may be temporary migration helpers. During upgrades, compare the framework selection with the addon list and remove duplicated framework-specific packages only when the current framework package already owns that behavior. Keeping obsolete addons can create confusing overlaps, while removing active project addons can silently disable panels, decorators, loaders, or preview setup that your stories depend on.

Sources: docs/_snippets/main-config-addons.md, docs/_snippets/nextjs-remove-addons.md

Runtime Addon Communication

The manager API snippets show that configuration is not limited to static files. Addons running in the manager can interact with the current Storybook state. The args example imports useArgs from the manager API and receives current args plus functions for updating and resetting them. Updating args is appropriate when addon UI should change the rendered story’s inputs, such as toggling a prop or simulating a control. Resetting named args supports targeted cleanup, while resetting with no names returns all args to their configured defaults.

Sources: docs/_snippets/args-usage-with-addons.md

Other manager APIs communicate with users and the browser location. The notification example registers an addon and calls addNotification with an identifier, headline, subheadline, optional icon, and duration. The query parameter example clears a parameter by setting it to null. These are runtime interactions, not replacements for main configuration. Use them for session-level feedback, UI state, or navigational cleanup. Use main config, presets, parameters, decorators, and globals when you need durable behavior that applies whenever the project starts.

Sources: docs/_snippets/storybook-addons-api-addnotification.md, docs/_snippets/storybook-addons-api-disablequeryparams.md

Practical Review Checklist

When reviewing a Storybook configuration, start with the main config and ask four questions. First, does the framework package match the application stack and builder expectation? Second, do the story globs include every intended story and MDX documentation file without pulling in unrelated files? Third, does each addon still serve a current purpose, and are object-style options scoped to the addon that owns them? Fourth, are runtime manager API calls being used for UI communication rather than for persistent project policy? That sequence keeps the configuration understandable as the project grows.

Sources: docs/_snippets/main-config-addons.md, docs/_snippets/args-usage-with-addons.md

Next, inspect presets and migration comments before assuming a missing behavior is a bug in stories. A preset may be injecting manager entries or preview annotations on behalf of an addon, so behavior can come from a package that is not listed as a simple addon string in the main config. Conversely, a framework migration may leave stale addon names behind, especially in Next.js projects that previously used separate Next-related addons. For deeper follow-up, read the framework-specific pages for integration defaults, the addons pages for authoring and presets, and the args and parameters pages for story-level configuration boundaries.

Sources: docs/_snippets/storybook-addon-load-external-addons-preset.md, docs/_snippets/nextjs-remove-addons.md

Ask a question...