Framework and Builder APIs

Purpose and Scope

Storybook framework and builder APIs exist so that Storybook can support many application stacks without making every project configure compilation, rendering, development servers, and framework-specific behavior by hand. A framework package represents an integration for either a metaframework, such as Next.js or SvelteKit, or a renderer-and-builder pairing, such as React with Vite or Angular with Webpack. A builder package is narrower: it compiles stories, components, CSS, MDX, and related project code into browser bundles, and it usually provides both a development server mode and a production build mode.

The official framework guidance describes a framework as the package that gives Storybook out-of-the-box support for a metaframework or a builder plus renderer combination. The official builder guidance describes builders as the layer that powers Storybook with Webpack, Vite, and similar tools. Read this page as an orientation for integration authors: it explains where those APIs fit in Storybook’s package model, how options are surfaced to users, and what conventions to follow when documenting extension points. The repository source path supplied for this page is an API reference for the MCP addon, so the source-grounded examples focus on option shape and documentation conventions rather than internal framework implementation files.

Sources: docs/ai/mcp/api.mdx

Relevant Source Files

• docs/ai/mcp/api.mdx — Shows Storybook’s API-reference documentation style for an extension package, including preview feature callouts, renderer-specific gating, main.js|ts registration language, typed option objects, defaults, and links to related resources.

The MCP API page is useful for framework and builder authors because it demonstrates the pattern Storybook uses when an extension exposes public configuration. It opens with a preview-status callout and a renderer support constraint, then documents options under the package name, explains where the user provides those options, lists TypeScript-like object shapes, and names each option with defaults and behavior. Framework and builder APIs should follow the same reader contract: identify package scope, state support boundaries, show the main.js|ts configuration surface, and make defaults explicit enough that users know what happens when they do nothing.

Sources: docs/ai/mcp/api.mdx

System-to-Code Mapping

At the product level, a Storybook framework package is the integration point a project selects in .storybook/main.js|ts. The framework tells Storybook which renderer to use, which builder to run, and which framework-specific defaults or compatibility layers should be applied. Metaframework packages can do more than wire a compiler; they can recreate or mock application features so that stories behave like components inside the target app. Builder packages sit beneath frameworks and are responsible for serving and bundling the preview iframe, which is where stories render in the browser.

The repository’s package architecture reflects that separation in its workspace layout: builders, frameworks, renderers, addons, presets, core, and scripts are distinct package families. The official builder docs describe Webpack, Vite, and ESBuild as examples of builder implementations, and the official framework docs define framework packages as installable Node packages. For a new integration, that means you should decide whether you are authoring a framework package, a builder package, or both. If you are only changing compilation and dev-server behavior, a builder API is the center of gravity. If you are adapting Storybook to an app framework’s conventions, a framework package is the public surface users will install.

The supplied API source illustrates how Storybook documents extension packages as named packages with typed options. In docs/ai/mcp/api.mdx, the public surface is @storybook/addon-mcp options, not an implementation module name. The page tells users that options are provided when registering the addon in main.js|ts, then defines the toolsets object. Framework and builder pages should use the same level of explicitness: name the package a user installs, name the configuration field a user edits, and separate package-level behavior from nested option behavior.

Sources: docs/ai/mcp/api.mdx

API Components

A framework integration normally exposes a package name for the framework field in Storybook configuration. The official docs use examples such as Vite-backed framework packages and metaframework packages, where the framework package bundles renderer and builder assumptions so users do not separately compose every lower-level piece. A builder integration is normally selected by dependency and configuration, either directly through a builder setting or indirectly through a framework package that chooses a builder. The builder API contract is about producing a running development environment and an optimized static build for the preview side of Storybook.

The MCP API page gives a compact example of how Storybook option references should be written. The top-level documented option is toolsets, with a TypeScript object shape containing optional dev, docs, and test booleans. The default object sets all three booleans to true. Each nested field then has its own subsection, type, default, and behavior. Framework and builder authors should mirror that pattern for configuration such as builder-specific paths, dev-server toggles, feature switches, or framework compatibility flags. Defaults matter because Storybook integrations are expected to work with minimal user configuration.

{
  dev?: boolean;
  docs?: boolean;
  test?: boolean;
}

The documented toolsets option also shows how to group functionality by user intent instead of implementation detail. dev enables tools for changed stories, story instructions, and previews; docs enables documentation discovery tools; test enables story test execution. A builder or framework API can use the same design principle: group options around what the user is trying to accomplish, such as locating an existing tool config, changing compilation output, or enabling framework features, rather than exposing a long list of internal pipeline switches first.

Sources: docs/ai/mcp/api.mdx

Execution Flow

A user-facing framework or builder flow begins during installation and configuration. The official builder docs explain that Storybook’s CLI detects the likely builder during initialization and can also accept an explicit builder choice. After installation, users edit .storybook/main.js or .storybook/main.ts to select the framework or builder package. At runtime, the framework layer supplies renderer and framework defaults, while the builder layer compiles the preview, serves it during development, and produces optimized assets for static output. This separation is what lets Storybook keep the authoring model consistent while supporting different app toolchains.

For integration authors, the practical flow is to start with the public package contract, then document the configuration surface before implementation details. If an option is experimental, renderer-specific, or limited to a subset of projects, put that constraint near the top. The MCP source does this with a preview callout that states Storybook’s AI capabilities and MCP server are currently only supported for React projects and that the API may change in future releases. Framework and builder APIs often have similar constraints, such as supported framework versions, required builder versions, or assumptions about project config files.

Once support boundaries are clear, describe the execution phases in the terms Storybook users already understand: development mode, static build mode, preview rendering, and docs generation when relevant. A builder should explain how it discovers or merges the user’s tool configuration, what Storybook must override, and which extension hook users can customize. A framework should explain which app-framework features it emulates, configures, or intentionally does not support. The goal is to make integration behavior predictable before a user reaches for an escape hatch.

Sources: docs/ai/mcp/api.mdx

Implementation Details and Documentation Conventions

The strongest API references in this repository combine typed shapes, defaults, and task-oriented explanation. In the MCP page, the toolsets section starts with a type block, follows with a default block, and then explains that the object toggles which MCP server toolsets are enabled. The nested sections repeat the same pattern for dev, docs, and test. This layout is especially important for framework and builder packages because users often copy configuration into .storybook/main.js|ts; ambiguous defaults can lead to duplicated settings, incompatible custom config, or assumptions that differ between development and production builds.

A framework or builder API page should also distinguish local project configuration from Storybook extension options. For builders, official docs emphasize that the builder compiles code and provides the dev server and production bundling path. That means options should be documented in relation to those phases: what affects dev startup, what affects hot updates, what affects static output, and what affects source transformation. For frameworks, options should be documented in relation to renderer behavior and app-framework compatibility. If a framework chooses a builder internally, say so, but avoid making users learn the internal builder package unless they need an override.

The MCP source ends with a short related-resources list that sends readers to setup, overview, sharing, best practices, and manifests. Framework and builder references benefit from the same navigation pattern. After readers understand the API surface, they usually need one of three next steps: install an existing integration, customize an existing builder, or contribute a new framework. Cross-linking those tasks keeps an API reference from becoming a dead end and gives maintainers a place to put migration or support-boundary details without overloading the option table.

Sources: docs/ai/mcp/api.mdx

Compact Reference

A concise framework or builder reference should name the package, show installation or selection, list configuration fields, describe default behavior, and explain how the integration participates in Storybook’s development and build lifecycle. Use examples only after defining the terms: framework, builder, renderer, preview, development mode, and production build. When writing a new page, also include migration notes if the package replaces another builder or framework, because users often arrive at these APIs while changing toolchains.

Next Steps

If you are consuming Storybook rather than authoring an integration, start with the framework page for your application stack and then read the Vite or Webpack builder documentation only when you need deeper build customization. If you are implementing a new integration, decide first whether the package is a framework, a builder, or a preset-like layer that composes existing packages. Then write the public API documentation before exposing many options: define the default path, document support limits, and keep escape hatches small enough that future Storybook releases can evolve the integration safely.

For source-backed documentation style, review the MCP API page’s structure: preview callout, renderer condition, package options, typed toolsets object, default values, nested option behavior, and related resources. That structure is a good template for any Storybook package API that needs to be understood by both application developers and maintainers. From here, continue to the builder-specific pages for Vite and Webpack, the framework contribution guide, and addon or preset authoring references when your integration needs to extend manager UI, preview behavior, or documentation generation.

Sources: docs/ai/mcp/api.mdx