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.
| Surface | Purpose | Typical product result |
|---|---|---|
| Manager | Extends the Storybook application | Panels, toolbar controls, status views, and navigation |
| Preview | Extends story execution and rendering | Decorators, globals, parameters, and story reports |
| Preset | Extends Storybook setup and services | Build setup, preview annotations, and external services |
| Shared channel | Connects manager and preview | Commands, 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 path | Scope | Main use |
|---|---|---|
| Preset options | Storybook setup | Build, framework, and service setup |
| Parameters | Project, component, or story | Rules and per-story settings |
| Globals | Current Storybook session | Toolbar selections and live modes |
| Addon state | Addon UI lifecycle | Results 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.
| Integration | Product role | Main surfaces |
|---|---|---|
| Docs | Builds component documentation and code examples | Manager, preview, and preset |
| Accessibility | Checks rendered stories against accessibility rules | Manager and preview |
| Themes | Lets users switch themes while viewing stories or docs | Manager and preview |
| Vitest | Runs component tests from Storybook and shows their status | Manager, test provider, and Node tooling |
| MCP | Gives agents tools for stories, docs, tests, and accessibility | Preset and HTTP service |
| Links | Connects stories into demos and prototypes | Manager and preview |
| Onboarding | Helps new users learn to write stories | Manager and preset |
| Pseudo States | Lets users inspect CSS pseudo states | Manager 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.
- User-facing addons covers panels, toolbar tools, docs, accessibility, themes, and navigation features.
- Testing and agent addons covers Vitest, accessibility reporting, MCP, and agent-facing workflows.
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
| Trigger | Consequence | Guard |
|---|---|---|
| A source event arrives for a story that is no longer selected | The Code panel shows stale code for the current story | Match the event story ID before updating the panel |
| An async source transform finishes after a newer source or context is active | Old code replaces the current source | Accept results only while the transform is active |
| A manager feature runs in an unsupported view | The UI shows a control with no valid target | Filter the feature by view mode and parameters |
| A vision global names an unknown simulator or a story view is not active | The simulator has no effect or leaves the wrong body filter | Validate the global, apply only in the story view, and restore the non-addon filter |
| A parameter or global disables a preview check | Expected work is skipped without a matching status | Keep skip rules in the addon configuration and report model |
An inline Docs Story block displays a story that mounts inside play without autoplay | The example cannot render in the docs block | Require autoplay for that story shape or use the iframe mode |
| A docs entry has no attached or standalone classification | The page is absent from the docs manifest views | Assign the intended docs classification before publishing manifest data |
| A service-backed docs manifest is treated as full content | A consumer cannot resolve the page body from the manifest alone | Resolve the documented reference through the MDX service |
| A composed ref has no valid component manifest | The agent cannot use that ref as a source | Probe refs at startup and omit missing or invalid sources |
| A composed ref is unreachable during startup | The source is unavailable until the next Storybook start | Apply a probe timeout and report that the ref was skipped |
| A remote manifest returns an expired or invalid bearer token | The agent receives an authentication error instead of source data | Forward the bearer token and clear cached data when the token changes |
| Composed refs use different OAuth servers | One authentication flow cannot cover every private ref | Use the first discovered OAuth server and warn about mismatches |
| The selected MCP tool group has no active feature support | An agent sees tools that cannot serve the Storybook session | Derive tool registration and instructions from effective availability |
| An MCP client requests unknown tool groups | The request can change the intended tool set | Ignore invalid names and enable only valid requested groups |
| An MCP request runs while the server is still initializing | Concurrent requests can create different tool or feature views | Share one initialization promise for the first server setup |
| A tool call finds an auth error only while its response body is consumed | The HTTP client receives a normal response instead of an auth challenge | Consume the tool response before mapping auth errors to 401 with WWW-Authenticate |
| A test run has failed checks or unhandled errors | The report can look complete but the run is marked as passed | Compute success from component failures, enabled accessibility failures, and unhandled errors |
| A response depends on an initial global that the test project does not provide | The story sees an empty or different value and the test result is misleading | Provide 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 timeout | The caller waits for the wrong run or hangs until external cleanup | Match request IDs and reject after the run timeout |
| A test run is cancelled or cannot start | No valid test verdict exists | Return an error outcome and do not emit completed-run telemetry |
| A test request selects no stories | No checks run and the user may mistake this for a pass | Return an explicit no-stories result with the selector reason |
| Accessibility is unavailable or disabled | An agent expects accessibility data that cannot exist | State whether accessibility was not enabled or was skipped |
| An MCP request has an invalid origin or media type | The request can bypass the expected HTTP boundary or fail in a confusing way | Reject disallowed origins and require application/json before dispatch |
Key files
| File | Why to read it |
|---|---|
| docs/…/writing-addons.mdx | Explains the broad addon model and extension surfaces |
| docs/…/addons-api.mdx | Defines the public manager, preview, state, and channel concepts |
| docs/…/configure-addons.mdx | Explains addon configuration and cross-surface communication |
| docs/…/main-config-addons.mdx | Shows how users register addons in Storybook configuration |
| code/…/index.ts | Shows the public preview extension surface |
| code/…/PreviewWithSelection.tsx | Shows how manager selection becomes a story or docs render |
| code/…/layout.ts | Shows the manager layout contract for panels, navigation, focus, and responsive behavior |
| code/…/manager.tsx | Shows an addon that registers manager panel and tool surfaces |
| code/…/A11yContext.tsx | Shows cross-surface accessibility state, reports, and channel events |
| code/…/withVisionSimulator.ts | Shows how a preview global changes story rendering while preserving other filters |
| code/…/store.ts | Shows addon-local state for fast-changing manager results |
| code/…/manager.tsx | Shows a manager panel that follows view and parameter rules |
| code/…/manifest.ts | Shows how attached and standalone documentation data reaches Storybook manifests |
| code/…/manifest.test.ts | Shows the manifest contract for summaries, references, and missing source files |
| code/…/CodePanel.tsx | Shows channel-driven source display and stale-story protection |
| code/…/Story.tsx | Shows inline and iframe story rendering in Docs blocks |
| code/…/Source.tsx | Shows the user-facing source block contract |
| code/…/docspage.md | Explains the user-facing documentation product |
| code/…/definition.ts | Shows the public test tool contract and outcome model |
| code/…/run.ts | Shows story selection, channel runs, serialization, and timeout handling |
| code/…/definition.test.ts | Shows the shared report contract for CLI and MCP consumers |
| code/…/InitialGlobals.stories.tsx | Shows config-provided globals reaching a composed test story |
| code/…/preset.ts | Shows MCP routes, feature-aware tool availability, and request guards |
| code/…/mcp-handler.ts | Shows MCP server initialization, per-request tool selection, and auth response handling |
| code/…/resolve-composition-sources.ts | Shows how configured refs become usable MCP sources |
| code/…/composition-auth.ts | Shows manifest access, OAuth discovery, caching, and remote source handling |