Introducing a new way to review your PRs.

Read the announcement

storybookjs / storybook

Storybook is the industry standard workshop for building, documenting, and testing UI components in isolation

View on GitHub

20 documents · Updated Nov 20, 2026

docs / addon-ecosystem

Addon ecosystem

Storybook addons extend one component workspace across its user interface, story preview, build setup, tests, and agent tools. The addon model keeps these roles separate while giving them shared configuration and an event channel so that one user action can affect the right environment and return a useful result.

Addon model

An addon is a package that adds a capability to a Storybook. A project enables addons in its Storybook configuration. The package can then provide only the surfaces that its capability needs.

SurfacePurposeTypical product result
ManagerExtends the Storybook applicationPanels, toolbar controls, status views, and navigation
PreviewExtends story execution and renderingDecorators, globals, parameters, and story reports
PresetExtends Storybook setup and servicesBuild setup, preview annotations, and external services
Shared channelConnects manager and previewCommands, events, and results across the preview boundary

References: docs/…/writing-addons.mdx• L16-21 docs/…/main-config-addons.mdx• L7-13 code/…/package.json• L37-50

Extension surfaces

The manager and preview are separate environments with different jobs. The manager owns the surrounding application. The preview owns the selected story and its render, so an addon uses the surface where its work must happen.

Manager surface

The manager surface makes an addon visible to the person using Storybook. It can add panels and toolbar tools. It can also react to the current story, view mode, globals, and addon state.

Manager features stay conditional when they apply only to a particular view or story. For example, the Docs code panel appears for story views and can be disabled by its docs setting. This keeps controls tied to a valid preview target instead of showing UI that cannot work in the current view. code/…/manager.tsx• L8-31

The layout surface lets addons work with panels, navigation, toolbars, fullscreen mode, focus, and responsive navigation. It changes the workspace around the story without making the addon responsible for the full application shell.

References: code/…/manager.tsx• L8-31 code/…/layout.ts• L50-149 code/…/layout.ts• L269-405 docs/…/addon-types.mdx• L9-31 code/…/manager.tsx• L36-51

Preview surface

The preview surface changes how stories run and how their results appear. It can set project defaults, add decorators, read parameters and globals, and run work after a story finishes.

The preview also owns story and docs rendering. It receives selection changes from the manager, prepares the matching render, and reports render and state changes through the channel. This lets an addon affect the story without placing story logic in the manager.

Accessibility uses this surface to apply a vision simulator and run checks after a story. The simulator reads the current vision mode from globals, preserves other body filters, and removes its own filter when the mode changes or the story view is not active. Themes use the same surface to apply the selected theme while the manager provides the toolbar control. Both packages expose separate preview entry points so the preview work can load without the manager UI. code/…/package.json• L43-50 code/…/package.json• L43-50

References: code/…/index.ts• L3-28 code/…/PreviewWithSelection.tsx• L90-218 code/…/PreviewWithSelection.tsx• L277-305 code/…/PreviewWithSelection.tsx• L332-539 code/…/A11yContext.tsx• L114-152 code/…/withVisionSimulator.ts• L15-62 code/…/package.json• L37-50 code/…/package.json• L37-50

Preset surface

The preset surface prepares Storybook before the browser surfaces start. It can add preview annotations, change build behavior, and provide services. This makes an addon useful even when it has no visible panel.

The MCP addon uses this surface to expose Storybook tools through an HTTP endpoint. Its tool groups follow addon options and the features available in the current Storybook. It can serve local data and valid composed Storybook sources. code/…/preset.ts• L28-76 code/…/preset.ts• L195-247

The endpoint supports a browser status page as well as MCP requests. It checks request origin and content type before it passes a request to the MCP service. Private composed sources add an OAuth challenge when a bearer token is required. code/…/preset.ts• L109-146 code/…/preset.ts• L164-212

References: docs/…/addon-types.mdx• L45-51 code/…/package.json• L26-52 code/…/README.md• L11-29 code/…/preset.ts• L79-212 code/…/preset.ts• L215-335

Shared channel

The channel is the event path between the manager and preview. It uses named events so an addon can publish a result in one environment and consume it in the other without coupling the preview to the manager UI.

When an addon handles a cross-boundary action, the flow is:

sequenceDiagram
    participant User
    participant Manager
    participant Channel
    participant Preview
    User->>Manager: Select story or use addon control
    Manager->>Channel: Emit command or request
    Channel->>Preview: Deliver event
    Preview->>Channel: Emit result or status
    Channel->>Manager: Deliver result
    Manager->>User: Show panel state or notification

The channel carries transient messages. Addons use parameters, globals, or addon state when a value must describe the current story or remain available across UI changes.

The accessibility addon illustrates this boundary. Its manager context listens for story completion and render-phase events. It sends manual runs and highlight actions to the preview. It accepts a report only for the active story, which keeps a late result from changing the current panel. code/…/A11yContext.tsx• L225-326

The Docs source flow illustrates the same boundary. The preview or docs block emits a source snippet with its story ID and language. The manager code panel ignores a late snippet for a story that is no longer selected. This prevents slow work for the previous story from replacing the current code. code/…/CodePanel.tsx• L43-85

References: docs/…/configure-addons.mdx• L35-43 docs/…/addons-api.mdx• L42-48 code/…/A11yContext.tsx• L307-326 code/…/CodePanel.tsx• L43-85 code/…/SourceContainer.tsx• L35-101 code/…/useTransformCode.tsx• L15-57

Configuration and state

Addon behavior is shaped by data at different scopes. Preset options set up Storybook. Parameters describe behavior for a project, component, or story. Globals represent values that a user can change while browsing. Addon state holds data shared by the addon UI during its lifecycle.

Data pathScopeMain use
Preset optionsStorybook setupBuild, framework, and service setup
ParametersProject, component, or storyRules and per-story settings
GlobalsCurrent Storybook sessionToolbar selections and live modes
Addon stateAddon UI lifecycleResults and other manager data

This split lets one addon keep stable project rules separate from live controls. Themes store the selected theme as a global. Accessibility uses parameters and globals to decide whether checks run and how their result appears. Its local store keeps fast-changing reports and panel state separate from broader manager state. code/…/store.ts• L6-58

References: docs/…/configure-addons.mdx• L10-26 docs/…/addons-api.mdx• L253-275 code/…/A11yContext.tsx• L114-152 code/…/store.ts• L28-58 code/…/package.json• L37-50

First-party integrations

First-party addons apply the extension model to the main ways teams use Storybook. They help people inspect and document stories. They connect stories to tests. They also expose Storybook data to agents.

IntegrationProduct roleMain surfaces
DocsBuilds component documentation and code examplesManager, preview, and preset
AccessibilityChecks rendered stories against accessibility rulesManager and preview
ThemesLets users switch themes while viewing stories or docsManager and preview
VitestRuns component tests from Storybook and shows their statusManager, test provider, and Node tooling
MCPGives agents tools for stories, docs, tests, and accessibilityPreset and HTTP service
LinksConnects stories into demos and prototypesManager and preview
OnboardingHelps new users learn to write storiesManager and preset
Pseudo StatesLets users inspect CSS pseudo statesManager and preview

Documentation integration

The Docs addon turns stories and component metadata into a component documentation page. Its default DocsPage combines descriptions, props information, stories, and code examples. Its blocks also support focused story previews and source display. A Story block can render the example inline or in an iframe. Inline rendering keeps the story in the docs layout and reports loading or render errors without losing its space. code/…/docspage.md• L5-29

The addon also publishes documentation metadata for other Storybook services. Attached pages appear with their component. Standalone pages appear in a separate docs view. Each page can provide its content and a summary, while a service-backed mode can publish a reference to the full MDX data instead of copying that content into the manifest. Pages without an attached or standalone classification do not enter these views. code/…/manifest.ts• L67-120 code/…/manifest.ts• L172-247

Stories that mount inside play need autoplay when shown inline. Without it, the block explains why it cannot display the example instead of starting a render that cannot complete in that context. code/…/Story.tsx• L121-149

The source block presents the selected example as readable code. It supports an explicit code override, a chosen language, formatting, copying, a loading state, and a warning when the example is incomplete. This gives generated source and authored source the same user-facing display contract. code/…/Source.tsx• L35-58 code/…/Source.tsx• L106-164

References: code/…/package.json• L40-79 code/…/docspage.md• L5-29 code/…/manifest.ts• L67-120 code/…/manifest.ts• L172-247 code/…/manifest.test.ts• L98-132 code/…/manifest.test.ts• L207-302 code/…/Story.tsx• L38-149 code/…/Source.tsx• L35-58 code/…/Source.tsx• L106-164

Testing integration

The Vitest addon brings test control and status into Storybook. Its public test tool can run selected stories or all available stories. It supports story, file, and changed-story selection. It returns a clear no-stories result when a selector matches nothing, and it can include accessibility results when the accessibility addon is enabled. code/…/definition.ts• L148-188

The tool sends each run through the shared channel and waits for the matching terminal response. A request ID prevents another run's response from being used. A queue allows one live test run at a time, while a timeout turns a missing response into an error. code/…/run.ts• L16-142

The test contract treats failed assertions, unhandled errors, and error-level accessibility results as a failed run. It keeps the report with the failure so a person or agent can act on the same story-level detail. Runs are serialized for one tool registration so concurrent requests do not control the same live test run at once. code/…/definition.ts• L217-297

Vitest setup can also seed initial globals for composed stories. This lets a test project check behavior that depends on config-provided globals before a user changes them in the Storybook UI. The InitialGlobals story verifies that this config value reaches the story and remains available to its test. code/…/InitialGlobals.stories.tsx• L7-29

References: code/…/package.json• L40-66 code/…/definition.ts• L121-188 code/…/definition.ts• L217-297 code/…/run.ts• L144-317 code/…/InitialGlobals.stories.tsx• L7-29

Agent integration

The MCP addon exposes Storybook capabilities through tool groups. The default endpoint is /mcp, and a project can set another URL path. The available groups reflect the active features and the groups requested by the client. code/…/README.md• L11-29 code/…/preset.ts• L215-247

The service initializes its tool set from effective Storybook feature availability. A client can narrow the active groups with the X-MCP-Toolsets request header. The server keeps one initialization promise for concurrent first requests, then passes the request path, source access, and composition auth into the tool call. code/…/mcp-handler.ts• L25-73 code/…/mcp-handler.ts• L114-153

The service can provide development, documentation, and test tools. Documentation tools use component and docs manifests. When Storybook composition is configured, the service probes refs and keeps only sources with valid manifests. It places the local source first and keeps the configured order for usable remote sources. code/…/resolve-composition-sources.ts• L13-31 code/…/composition-auth.ts• L81-126

Private refs use OAuth discovery and bearer tokens. Remote manifest data is cached for a short period and refreshed in the background. A new token clears the cache so an agent does not reuse data from an earlier login. code/…/composition-auth.ts• L147-243

The test tool keeps its contract aligned for CLI and MCP consumers. It gives both consumers the same report and marks the outcome as failed when the selected checks fail. When accessibility is not enabled or is skipped, the result says so instead of promising a report that it cannot provide. code/…/definition.test.ts• L112-155 code/…/definition.test.ts• L288-329

References: code/…/package.json• L26-52 code/…/server.json• L28-45 code/…/preset.ts• L215-335 code/…/mcp-handler.ts• L25-73 code/…/mcp-handler.ts• L114-172 code/…/resolve-composition-sources.ts• L13-31 code/…/composition-auth.ts• L81-126 code/…/composition-auth.ts• L147-243 code/…/definition.ts• L121-177 code/…/definition.test.ts• L112-155

Ecosystem navigation

Addon work splits into two paths. User-facing addons change how people view, inspect, document, and navigate stories. Testing and agent addons connect stories to automated checks, test runners, and external tools.

References: docs/…/addon-types.mdx• L9-51 code/…/definition.ts• L150-177 code/…/package.json• L26-52

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep manager and preview entry points aligned when an addon adds or removes a cross-surface feature.
  • Keep channel event names, story identity, and payload meaning aligned between the producer and consumer.
  • Keep parameter, global, and addon-state keys aligned with the controls and with the rules that consume them.
  • Keep vision-simulator filter names, body-filter cleanup, view visibility, and injected filter definitions aligned with the preview global.
  • Keep docs story rendering mode, autoplay requirements, loading state, error state, and story layout behavior aligned across inline and iframe paths.
  • Keep docs source precedence, language selection, async transforms, and stale-result handling aligned across the preview and Code panel.
  • Keep docs manifest classification, component attachment, standalone docs entries, summaries, and service references aligned with the consumers that read docs data.
  • Keep manager view and layout checks aligned with panel, toolbar, fullscreen, and responsive navigation behavior.
  • Keep test selectors, changed-story resolution, channel request IDs, terminal statuses, timeout behavior, and report meaning aligned across the tool boundary.
  • Keep initial-global setup aligned with the globals received by composed stories and with tests that require a seeded value.
  • Keep test tool input, accessibility availability, run outcome, report text, and telemetry aligned across CLI and MCP consumers.
  • Keep MCP tool-group selection aligned with addon options, feature gates, manifest access, composed sources, and request headers.
  • Keep composed-source probing, manifest validation, source order, bearer-token forwarding, and cache invalidation aligned across composition and MCP request handling.
  • Keep OAuth resource metadata and endpoint paths aligned with the configured base path and custom MCP endpoint.
  • Keep addon package exports and peer dependencies aligned with the manager, preview, preset, and external service surfaces that Storybook loads.

Important failure modes

TriggerConsequenceGuard
A source event arrives for a story that is no longer selectedThe Code panel shows stale code for the current storyMatch the event story ID before updating the panel
An async source transform finishes after a newer source or context is activeOld code replaces the current sourceAccept results only while the transform is active
A manager feature runs in an unsupported viewThe UI shows a control with no valid targetFilter the feature by view mode and parameters
A vision global names an unknown simulator or a story view is not activeThe simulator has no effect or leaves the wrong body filterValidate the global, apply only in the story view, and restore the non-addon filter
A parameter or global disables a preview checkExpected work is skipped without a matching statusKeep skip rules in the addon configuration and report model
An inline Docs Story block displays a story that mounts inside play without autoplayThe example cannot render in the docs blockRequire autoplay for that story shape or use the iframe mode
A docs entry has no attached or standalone classificationThe page is absent from the docs manifest viewsAssign the intended docs classification before publishing manifest data
A service-backed docs manifest is treated as full contentA consumer cannot resolve the page body from the manifest aloneResolve the documented reference through the MDX service
A composed ref has no valid component manifestThe agent cannot use that ref as a sourceProbe refs at startup and omit missing or invalid sources
A composed ref is unreachable during startupThe source is unavailable until the next Storybook startApply a probe timeout and report that the ref was skipped
A remote manifest returns an expired or invalid bearer tokenThe agent receives an authentication error instead of source dataForward the bearer token and clear cached data when the token changes
Composed refs use different OAuth serversOne authentication flow cannot cover every private refUse the first discovered OAuth server and warn about mismatches
The selected MCP tool group has no active feature supportAn agent sees tools that cannot serve the Storybook sessionDerive tool registration and instructions from effective availability
An MCP client requests unknown tool groupsThe request can change the intended tool setIgnore invalid names and enable only valid requested groups
An MCP request runs while the server is still initializingConcurrent requests can create different tool or feature viewsShare one initialization promise for the first server setup
A tool call finds an auth error only while its response body is consumedThe HTTP client receives a normal response instead of an auth challengeConsume the tool response before mapping auth errors to 401 with WWW-Authenticate
A test run has failed checks or unhandled errorsThe report can look complete but the run is marked as passedCompute success from component failures, enabled accessibility failures, and unhandled errors
A response depends on an initial global that the test project does not provideThe story sees an empty or different value and the test result is misleadingProvide the global in the Vitest setup and keep the story scoped to that setup
A test response belongs to another request or does not arrive before the timeoutThe caller waits for the wrong run or hangs until external cleanupMatch request IDs and reject after the run timeout
A test run is cancelled or cannot startNo valid test verdict existsReturn an error outcome and do not emit completed-run telemetry
A test request selects no storiesNo checks run and the user may mistake this for a passReturn an explicit no-stories result with the selector reason
Accessibility is unavailable or disabledAn agent expects accessibility data that cannot existState whether accessibility was not enabled or was skipped
An MCP request has an invalid origin or media typeThe request can bypass the expected HTTP boundary or fail in a confusing wayReject disallowed origins and require application/json before dispatch

Key files

FileWhy to read it
docs/…/writing-addons.mdxExplains the broad addon model and extension surfaces
docs/…/addons-api.mdxDefines the public manager, preview, state, and channel concepts
docs/…/configure-addons.mdxExplains addon configuration and cross-surface communication
docs/…/main-config-addons.mdxShows how users register addons in Storybook configuration
code/…/index.tsShows the public preview extension surface
code/…/PreviewWithSelection.tsxShows how manager selection becomes a story or docs render
code/…/layout.tsShows the manager layout contract for panels, navigation, focus, and responsive behavior
code/…/manager.tsxShows an addon that registers manager panel and tool surfaces
code/…/A11yContext.tsxShows cross-surface accessibility state, reports, and channel events
code/…/withVisionSimulator.tsShows how a preview global changes story rendering while preserving other filters
code/…/store.tsShows addon-local state for fast-changing manager results
code/…/manager.tsxShows a manager panel that follows view and parameter rules
code/…/manifest.tsShows how attached and standalone documentation data reaches Storybook manifests
code/…/manifest.test.tsShows the manifest contract for summaries, references, and missing source files
code/…/CodePanel.tsxShows channel-driven source display and stale-story protection
code/…/Story.tsxShows inline and iframe story rendering in Docs blocks
code/…/Source.tsxShows the user-facing source block contract
code/…/docspage.mdExplains the user-facing documentation product
code/…/definition.tsShows the public test tool contract and outcome model
code/…/run.tsShows story selection, channel runs, serialization, and timeout handling
code/…/definition.test.tsShows the shared report contract for CLI and MCP consumers
code/…/InitialGlobals.stories.tsxShows config-provided globals reaching a composed test story
code/…/preset.tsShows MCP routes, feature-aware tool availability, and request guards
code/…/mcp-handler.tsShows MCP server initialization, per-request tool selection, and auth response handling
code/…/resolve-composition-sources.tsShows how configured refs become usable MCP sources
code/…/composition-auth.tsShows manifest access, OAuth discovery, caching, and remote source handling