Framework packages
Framework packages connect Storybook to a UI framework and its project toolchain. They select the builder and renderer, add framework preview behavior, and adapt project files so stories can run with the same core framework features as the application.
This page fits under Framework and build integration. For adjacent concerns, see Builder integrations, Renderer packages, and Webpack presets.
Package role
Each package provides a framework-facing entry point and a preset. The entry point exposes the framework story API and typed preview helpers. The preset composes the builder with the matching renderer, then adds only the project integration that the framework needs. Documentation extraction is part of that contract when a framework can expose component metadata.
The common contract is:
| Concern | Framework package responsibility |
|---|---|
| Story execution | Select the renderer that mounts the framework components. |
| Build and serve | Select Vite or webpack and pass through framework options. |
| Preview setup | Add annotations, mocks, or preview add-ons for framework APIs. |
| Project behavior | Reuse or adapt the application's compiler, styles, assets, aliases, and server-only boundaries. |
| Component information | Connect framework-aware documentation or metadata when the package supports it. |
References: code/…/preset.ts• L10-13 code/…/index.ts• L1-4 code/…/preset.ts• L3-6
Preset composition
The preset is the package's link to Storybook's framework-and-build system. Most packages declare a core preset with a builder and renderer. More advanced packages extend that base with build plugins, preview annotations, documentation extraction, or dependency optimization rules. These additions are conditional when the same work is handled by the server-side documentation path.
The composition follows this shape:
flowchart LR
A[Framework package] --> B[Core preset]
B --> C[Builder]
B --> D[Renderer]
A --> E[Preview annotations and add-ons]
A --> F[Build configuration]
F --> G[Framework application]
C --> H[Storybook preview]
D --> H
E --> H
Simple targets such as HTML and web components only need the builder and renderer mapping. React, Vue, Svelte, and Angular add build or metadata work because their application models include a compiler or component information system. Next.js and SvelteKit add more preview work because their application models also include routing or server boundaries.
References: code/…/preset.ts• L3-6 code/…/preset.ts• L3-6 code/…/preset.ts• L9-36 code/…/preset.ts• L17-20
Application integration
Framework packages make Storybook behave like a small, isolated application that uses the project's framework rules. They merge project configuration into the Storybook preview instead of treating stories as generic JavaScript modules.
The main integration areas are:
- Compilation: Framework transforms compile component syntax and story files.
- Runtime context: Preview annotations provide framework providers, mocks, routing behavior, or production-mode setup.
- Styles and assets: The preset brings application style entries, preprocessors, public assets, and CSS conventions into the preview.
- Module boundaries: Server-only imports and framework-specific modules are removed, mocked, or redirected when the preview runs in a browser.
- Metadata: Documentation providers extract component inputs, outputs, props, or slots for controls and component manifests. Builder-side extraction runs only when the server-side path is not active.
Angular also carries workspace style rules into the preview and checks that the required style preprocessor is available. Its integration keeps workspace-relative styles distinct from the Storybook Vite root. The renderer can update story properties without a full application restart when the story template and module metadata stay the same; it performs a full bootstrap when either changes and cleans up the prior Angular application first. The Vite path supports zoneless change detection through its current runtime option, while the older Angular path keeps its compatibility check for Angular versions that support that mode.
Angular documentation has two related outputs. The webpack package can use Compodoc when its builder path needs it. The Angular Vite package now extracts Angular metadata in-process, so its legacy Compodoc options are retained only as deprecated no-op compatibility fields. When the documentation server is active, the Vite preset skips a second scan and can supply an empty compatibility document for the generated preview import. The Angular story-docs provider resolves the component and declared subcomponents from the story's import graph, then returns controls data, API data, and snippet metadata. A missing component lets another provider handle the story, while an unreadable declared component reports an extraction error.
The provider also reads story markup when it can do so without running the story. It can represent literal template values, render results, CSF2 stories, and the common argsToTemplate pattern in generated snippets. Dynamic expressions remain unresolved instead of being presented as if they were static markup.
Angular's Vitest bridge carries Angular build options into standalone browser tests and permits dependency roots from nested Angular workspaces, so a library project can use compiler packages installed at the workspace level without breaking the browser test server. The Angular Vite test setup loads the Angular compiler before it initializes the dynamic test environment. The shared Angular test setup initializes that environment without owning the Vite compiler preload.
References: code/…/preset.ts• L28-41 code/…/preset.ts• L84-161 code/…/preset.ts• L232-247 code/…/AbstractRenderer.ts• L36-163 code/…/AbstractRenderer.ts• L35-167 code/…/build-docgen.ts• L91-115 code/…/build-docgen.ts• L259-363 code/…/resolve-component.ts• L23-68 code/…/story-docs-markup.ts• L137-171 code/…/story-docs-markup.ts• L292-377 code/…/vitest.ts• L33-43 code/…/vitest.ts• L64-121 code/…/vitest-compiler-setup.ts• L1-6 code/…/test-setup.ts• L1-11 code/…/test-setup.ts• L1-8 code/…/build-schema.json• L61-72 code/…/start-schema.json• L83-94 code/…/vue-component-meta.test.ts• L104-153 code/…/vue-component-meta.test.ts• L310-378
Framework families
The packages share the same Storybook contract but differ in the application boundary they reproduce. The following groups describe the important product role of each target.
React packages
React packages provide the React renderer through either Vite or webpack. The Vite package adds builder-side React metadata extraction only when server-side extraction is not active. Its public configuration types expose builder options and React-specific preview settings, while the older builder docgen settings remain available as deprecated compatibility options during the move to server-side documentation. The webpack package supplies the React webpack preset and keeps the React package identity stable through an alias.
React Native Web and TanStack React build on the React Vite package. React Native Web adds the bridge needed to use React Native components in a web preview. TanStack React adds preview support for router behavior and removes or replaces server-only application modules. The React starter example uses normal React style props, so it remains a base case for framework integration.
References: code/…/preset.ts• L10-71 code/…/types.ts• L11-30 code/…/types.ts• L32-88 code/…/Button.jsx• L1-25 code/…/package.json• L50-76 code/…/package.json• L53-85 code/…/preset.ts• L25-57
Angular packages
Angular has separate webpack and Vite packages because the build path and application integration differ. Both expose Angular preview behavior and skip Storybook's generic TypeScript compiler. The Vite package adds Angular compilation, workspace aliases, styles, zone mode, mock handling, and component documentation support. It enables the components manifest feature, but that manifest depends on the server documentation path.
The package keeps Angular application behavior visible to the preview. It loads workspace styles from the Angular workspace root and supports the style preprocessor names that Angular projects use. Its documentation flow can produce component manifests while avoiding a second generation pass when server-side extraction is active. The Vite builder schemas keep the start and build commands aligned, including shared log-level validation and path-or-boolean statistics options. The webpack package retains the separate Compodoc controls used by its build path.
The story-docs output also keeps a stable Angular component API for generated descriptions and snippets. It documents the main component and can document subcomponents under the names used by the story meta. If a story has no Angular component, the provider yields to another provider; if a declared component cannot be read, it reports an extraction error instead of hiding the failure.
The Vite package also exposes a Vitest entry point for Angular browser tests. That entry point passes build options through a stable environment channel, registers a wrapper that evaluates the Angular compiler once per test page, and allows all ancestor dependency roots needed by nested workspaces. This keeps standalone Vitest runs aligned with the Storybook Angular build without registering the full Angular Vite plugin a second time.
References: code/…/preset.ts• L6-44 code/…/package.json• L27-47 code/…/preset.ts• L28-41 code/…/preset.ts• L115-147 code/…/AbstractRenderer.ts• L36-163 code/…/AbstractRenderer.ts• L35-167 code/…/vitest.ts• L45-121 code/…/vitest-compiler-setup.ts• L1-6 code/…/test-setup.ts• L1-11 code/…/test-setup.ts• L1-8 code/…/build-docgen.ts• L117-363 code/…/resolve-component.ts• L23-68 code/…/story-docs-markup.ts• L137-171 code/…/story-docs-markup.ts• L292-377 code/…/build-schema.json• L66-87 code/…/build-schema.json• L61-77 code/…/schemas.test.ts• L7-34 code/…/schemas.test.ts• L19-55
Vue packages
The Vue Vite package selects the Vue renderer and adds the Vue template compiler to the Vite pipeline. It chooses the builder-side documentation provider only when server-side extraction is not active. The default builder provider uses Vue's general documentation path, while the TypeScript-based component metadata path is used only when its compiler support is available.
This keeps Vue single-file component behavior and component information aligned with the story preview. The metadata path documents local component bindings rather than barrel re-exports. It also updates the preview when a component's props or slots change during development. The package exposes the Vue story API and the framework-specific definePreview helper through its public entry point.
References: code/…/preset.ts• L20-51 code/…/options.ts• L5-45 code/…/vue-component-meta.test.ts• L104-153 code/…/vue-component-meta.test.ts• L310-378 code/…/index.ts• L1-4
Svelte packages
The Svelte Vite package combines the Svelte renderer with Svelte component-file compilation and the Svelte CSF transform. The transform turns Svelte story files into runnable stories and keeps their styles when a production build would otherwise remove them. It adds builder-side component documentation only when it is enabled, server-side documentation is inactive, and the project has usable TypeScript support. Its docgen examples cover a main component and named subcomponents, which keeps related component APIs together in generated docs. SvelteKit extends this package for application-level behavior.
SvelteKit adds SvelteKit preview annotations, copies the application's static directory for production builds, and synchronizes Kit configuration with the Storybook preview. It replaces browser-facing Kit modules with story-controlled mocks for page state, navigation, and form actions, while blocking server-only modules. Each story starts from clean mock state, so a story can model a route, form result, navigation event, or update without changing the next story.
The SvelteKit preview also isolates docs stories that configure these mocks. Inline docs stories share one document and therefore cannot safely use different mock state. The framework reports this case and directs authors to render such stories in separate iframes. The old sveltekit_experimental parameter is rejected with a migration error; stories now configure the public mock functions and state in beforeEach.
References: code/…/preset.ts• L16-48 code/…/svelte-csf.ts• L10-49 code/…/options.ts• L5-19 code/…/subcomponents.stories.ts• L1-15 code/…/preset.ts• L17-62 code/…/index.ts• L20-35 code/…/preview.ts• L31-90 code/…/errors.ts• L6-51 code/…/forms.ts• L15-60 code/…/navigation.ts• L19-121 code/…/app-state-mock.svelte.js• L39-245 code/…/docs-page-isolated-mocks.stories.js• L5-24
Next.js packages
Next.js has webpack and Vite packages. Both provide the React renderer plus Next.js preview behavior. The webpack package adapts the Next configuration and supports framework features such as fonts, images, CSS, styled-jsx, aliases, fast refresh, and optional server components. The Vite package reuses React Vite integration and adds Next.js Vite plugins, mocks, styled-jsx aliases, and PostCSS handling.
The two packages keep the same Next.js-facing story model while serving different build paths. Their public entry points add Next-specific preview types and annotations. This lets stories use Next.js-facing APIs while the preset supplies browser-safe substitutes for application services. The export mocks preserve the real headers API and make cookies and headers available to stories while exposing draftMode as a spyable passthrough. The font path preserves the requested display setting for every generated local-font face and defaults it to swap, so local font behavior remains consistent with Next.js.
The Next.js starter example also uses styled-jsx, which shows why the package must preserve Next.js styling behavior rather than rely only on the base React setup.
References: code/…/package.json• L89-173 code/…/package.json• L90-133 code/…/preset.ts• L24-63 code/…/preset.ts• L148-204 code/…/preset.ts• L17-80 code/…/index.ts• L21-32 code/…/index.ts• L1-13 code/…/get-font-face-declarations.ts• L24-77 code/…/Button.jsx• L1-29
HTML and web component packages
HTML and web component packages are the thin end of the framework contract. They map Vite to the matching renderer and expose the renderer's story API. They do not need a framework compiler or application runtime layer because the browser can consume their component model directly.
References: code/…/preset.ts• L3-6 code/…/index.ts• L1-2 code/…/preset.ts• L3-6 code/…/index.ts• L1-4
Other target packages
Preact and related targets use the same package shape with different integration depth. Preact maps Vite to the Preact renderer and keeps a small package boundary. React Native Web builds on React Vite and adds a web compatibility layer for React Native components. TanStack React builds on the same React base and adds router and server-runtime mocks for its application services.
Ember and Server are webpack targets with a different application boundary. Ember adapts Babel and inline template compilation so Ember components can run in Storybook. Server renders HTML returned by a server-facing story rather than mounting a client framework. These packages show that a framework package can stay small when the renderer and builder already match the target, or add a focused bridge when the target has its own runtime or template rules.
References: code/…/preset.ts• L3-11 code/…/package.json• L28-63 code/…/package.json• L53-85 code/…/package.json• L31-67 code/…/package.json• L27-67 code/…/package.json• L26-59
Preview entry points
The public entry point is the application-facing side of a framework package. It re-exports the framework story types and usually exposes definePreview, which adds the package's preview annotations or add-ons to the user's project annotations.
This split keeps authoring concerns separate from build concerns. A story author imports the framework package for types and preview helpers. Storybook loads the preset to select builders and configure the application environment.
References: code/…/index.ts• L1-4 code/…/index.ts• L1-4 code/…/index.ts• L15-35 code/…/index.ts• L16-32
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the builder and renderer pair aligned with the package's supported application toolchain.
- When a package extends another framework preset, preserve the parent configuration before adding target-specific plugins.
- Keep preview annotations and public
definePreviewtypes aligned so runtime behavior and authoring types describe the same framework APIs. - When adding framework mocks or aliases, check both development and production preview paths.
- When changing documentation extraction, keep the server-side path and builder-side fallback mutually exclusive.
- When changing application styles or static assets, check both the framework's workspace root and Storybook's Vite root.
- When changing a framework's metadata provider, keep its compiler availability checks and fallback provider aligned with the server-side documentation mode.
- When changing framework-specific public types, keep the story arg shapes aligned with the framework's component inputs, outputs, and two-way bindings.
- When changing a story-file transform, preserve both the runnable story output and the component styles used by production builds.
- When changing Angular's renderer, keep the incremental property path separate from full bootstrap changes, and reset the prior application before replacing its root element.
- When changing Angular story selectors or story UIDs, keep generated HTML tags and CSS attribute selectors valid for non-ASCII story names.
- When changing Angular's Vitest or test setup, keep compiler preload, dynamic test initialization, and nested workspace dependency access aligned.
- When changing Angular documentation output, keep component controls, API descriptions, snippet metadata, and manifest generation on the same component resolution rules.
- When changing Angular's component resolver, keep main-component and subcomponent resolution errors distinct from stories that have no component.
- When changing Angular story markup extraction, preserve the boundary between statically readable markup and markup that requires story execution.
- When changing Angular's manifest feature, keep its dependency on server-side documentation clear in the preset and user-facing warning.
- When changing Angular builder schemas, keep the start and build option contracts aligned and preserve string-first types for options that accept either a path or a boolean.
- When changing React public configuration types, keep deprecated builder docgen options compatible with the server-side documentation migration.
- When changing Next.js local-font handling, preserve the
displayvalue for both single and multiple font sources and retain the default when it is omitted. - When changing Next.js export mocks, keep the real module exports and spyable framework behavior available to the preview.
- When changing SvelteKit mock exports, keep the
$app/forms,$app/navigation, and$app/statealiases pointed at the same mock instances used by the public mock entry points. - When changing SvelteKit story setup, keep per-story reset behavior and docs-page isolation aligned so one story cannot change another story's mock state.
- When changing SvelteKit package exports or build entries, keep browser and node entry points aligned with the published mock paths and generated state mock declaration.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A framework preset selects the wrong renderer or builder. | Stories fail to mount or the project compiler cannot process them. | Keep core mappings tied to the framework's renderer and supported build path. |
| Builder-side documentation runs while the server documentation path is active. | Metadata can be duplicated or the preview can carry unwanted build-time data. | Use the resolved documentation mode before adding docgen plugins. |
| Angular's components manifest is enabled while server-side documentation is off. | Storybook publishes no component manifest and clients receive no component API. | Keep the preset warning and the server documentation requirement aligned. |
| Angular style paths are resolved from the Vite root instead of the Angular workspace root. | Workspace styles fail to load in monorepos or nested Storybook projects. | Resolve Angular workspace-relative style entries against the workspace root. |
| An Angular story points to an unreadable component or a component import that cannot resolve. | Story docs report misleading or incomplete component information. | Resolve the component before extraction and return an explicit provider error when a declared component fails. |
| Angular reuses an application after its template or module metadata changed. | The preview shows stale structure or providers. | Require a full render when the template or metadata snapshot changes. |
| Angular replaces a story root without destroying the old application. | Views and injectors remain attached to detached DOM and can leak or fail during teardown. | Destroy component views while the injector is alive, then destroy the application. |
| An Angular story ID or UID becomes an invalid HTML tag or CSS selector. | The renderer cannot bootstrap the story root or find its component. | Sanitize tag and attribute identifiers and use stable fallbacks. |
| Angular Vitest runs without the early compiler setup. | Libraries that need JIT compilation fail before the test environment can render components. | Load the Angular compiler before test annotations and initialize the dynamic test environment once per worker. |
| Angular story-docs treats a dynamic template or render result as static. | Generated snippets show markup that does not match the story. | Emit only statically resolved markup and mark runtime-dependent expressions unresolved. |
| Vue metadata is injected for a re-export instead of a local component binding. | Controls or docs describe a barrel module rather than the rendered component. | Limit metadata injection to the component binding that belongs to the current module. |
| Vue metadata changes do not reach the preview HMR path. | Controls and docs stay stale until a full restart. | Reload the preview only when the component metadata or an importing component's metadata changes. |
| Svelte CSF output loses its style association. | A production preview renders Svelte stories without their component styles. | Preserve the transform's CSS scope metadata for story files. |
| A SvelteKit story changes shared mock state on an inline docs page. | Other stories render with the last story's page, navigation, or form setup. | Require iframe docs rendering when a story configures SvelteKit mocks. |
A SvelteKit story still uses sveltekit_experimental parameters. | The story stops before render and does not use the new mock contract. | Keep the migration error and the beforeEach mock guidance in the preview annotations. |
| SvelteKit server modules reach the browser preview. | The preview imports APIs that exist only in a SvelteKit server runtime. | Apply SvelteKit mocks and server-module guards in the Vite preset. |
| A SvelteKit mock alias uses a different module instance than its public mock entry point. | A story configures one mock while the component reads another. | Resolve aliases and public exports to the same forms, navigation, and state mocks. |
| Next.js application features are not represented in the preview. | Fonts, images, CSS, routing, or styled-jsx behave differently from the app. | Keep the Next.js webpack or Vite integration active with its preview mocks. |
| A local Next.js font's display setting is dropped or applied only to the first source. | Font loading behavior differs between one-source and multi-source local fonts. | Emit the validated display value for every generated @font-face block and default it to swap. |
Key files
| File | Why to read it |
|---|---|
| code/…/preset.ts | Shows the basic Vite framework preset and conditional React metadata integration. |
| code/…/types.ts | Shows the public React Vite configuration contract and the transition from builder docgen to server documentation. |
| code/…/preset.ts | Shows the deepest application integration for compiler, styles, mocks, and documentation. |
| code/…/AbstractRenderer.ts | Shows Angular application bootstrap, incremental story property updates, selector handling, and teardown. |
| code/…/AbstractRenderer.ts | Shows the compatibility Angular renderer and its version-gated zoneless behavior. |
| code/…/vitest.ts | Shows how Angular options and early compiler setup reach standalone Vitest browser runs. |
| code/…/vitest-compiler-setup.ts | Shows the stable compiler wrapper used by Angular browser tests. |
| code/…/test-setup.ts | Shows compiler preload and dynamic Angular test environment setup for the Vite path. |
| code/…/test-setup.ts | Shows the shared Angular dynamic test environment setup. |
| code/…/build-docgen.ts | Shows how Angular component metadata becomes controls, API descriptions, subcomponent data, and story-docs snippets. |
| code/…/resolve-component.ts | Shows how story metadata resolves its main component and declared subcomponents. |
| code/…/story-docs-markup.ts | Shows how readable Angular story markup becomes generated documentation snippets. |
| code/…/build-schema.json | Defines the Vite Angular builder's application and output option contract. |
| code/…/start-schema.json | Defines the Vite Angular start command and its shared workspace options. |
| code/…/schemas.test.ts | Protects the Angular Vite builder schema types and log-level contract. |
| code/…/build-schema.json | Defines the webpack Angular builder's application and documentation options. |
| code/…/start-schema.json | Defines the webpack Angular start command and its workspace options. |
| code/…/schemas.test.ts | Protects the webpack Angular builder schema log-level contract. |
| code/…/preset.ts | Shows how a framework compiler and metadata provider join the Vite pipeline. |
| code/…/vue-component-meta.test.ts | Summarizes how Vue metadata follows local exports and live preview updates. |
| code/…/preset.ts | Shows Svelte compilation, CSF transformation, and conditional builder documentation. |
| code/…/svelte-csf.ts | Shows how Svelte stories are transformed and how their CSS stays attached. |
| code/…/subcomponents.stories.ts | Shows the Svelte docgen shape for a main component and a named subcomponent. |
| code/…/preset.ts | Shows the SvelteKit builder, renderer, aliases, static assets, and server-module boundary. |
| code/…/index.ts | Shows the SvelteKit public preview entry point and its built-in annotations. |
| code/…/preview.ts | Shows per-story reset, docs isolation, link interception, and migration checks. |
| code/…/errors.ts | Shows the user-facing errors for removed parameters and shared docs mocks. |
| code/…/forms.ts | Shows the story-facing form action contract and form result behavior. |
| code/…/navigation.ts | Shows the story-facing navigation spies and configurable navigation lifecycle. |
| code/…/app-state-mock.svelte.js | Shows the page, navigation, and update state exposed to SvelteKit stories. |
| code/…/build-config.ts | Shows the published browser, node, and mock entry points. |
| code/…/package.json | Shows the SvelteKit package boundary and public mock exports. |
| code/…/forms.stories.js | Shows form success, failure, redirect, error, cancel, and custom callback behavior. |
| code/…/docs-page-isolated-mocks.stories.js | Shows iframe docs isolation for stories with separate SvelteKit mock state. |
| code/…/preset.ts | Shows webpack integration for a framework with many application services. |
| code/…/preset.ts | Shows reuse of React Vite integration with Next.js-specific plugins and aliases. |
| code/…/index.ts | Shows how Next.js request APIs stay available and spyable in the preview. |
| code/…/get-font-face-declarations.ts | Shows how local Next.js font options become preview CSS. |
| code/…/Button.jsx | Shows Next.js starter styling behavior through styled-jsx. |
| code/…/preset.ts | Shows the minimal Preact Vite preset. |
| code/…/package.json | Shows the package boundary for React Native Web's Vite compatibility layer. |
| code/…/package.json | Shows the React router and server-runtime package boundary. |
| code/…/package.json | Shows the Ember webpack package boundary and template compiler peers. |
| code/…/package.json | Shows the server-rendering framework package boundary. |
| code/…/preset.ts | Shows the minimal builder-to-renderer package shape. |
| code/…/preset.ts | Shows the minimal package shape for browser-native component targets. |