Renderer packages
Renderer packages connect Storybook's preview runtime to a UI technology. Each package turns a story into a framework value, mounts it in the preview canvas, reports render errors, and exposes typed preview helpers for stories, tests, and docs. See Framework packages for the application-facing layer, Builder integrations and Webpack presets for build selection, and Framework and build integration for the parent view.
Renderer package role
The renderer is the framework-facing part of Storybook's preview. Framework packages and builders select the renderer for a project. The preview runtime supplies story context and lifecycle callbacks such as showing the canvas, showing an error, forcing a remount, and cleaning up after a story change. The shared renderer contract describes the component type, story result, and optional mount API that each technology supports. code/…/renderers.ts• L1-15
The supported renderer names include React, React Native, Vue 3, Angular, Ember, Preact, Svelte, Qwik, HTML, Web Components, Server, Solid, and Nuxt. This is the runtime vocabulary that framework integration uses to map a project to a renderer. code/…/renderers.ts• L1-15
References: code/…/renderers.ts• L1-15 code/…/types.ts• L4-12 code/…/types.ts• L22-37
Story mounting lifecycle
The renderer receives a story result and places it in the canvas element. It keeps the canvas usable while stories change by updating an existing framework instance when safe, remounting when Storybook requests fresh component state, and returning cleanup work for the next story. Each UI system has its own mount and update model.
When a story is processed, the renderer follows this sequence:
- Storybook gives it the story function, story context, canvas element, and lifecycle callbacks.
- It turns the story into a framework value such as a React element, Vue component, Svelte component, DOM node, string, or Lit template.
- It mounts or updates that value in the canvas.
- It reports a ready canvas or sends a render error to the preview.
- It returns cleanup work so the preview can remove the story when it changes.
This diagram shows the boundary between the preview runtime and a renderer package.
flowchart LR
A[Preview runtime] -->|story context and lifecycle callbacks| B[Renderer package]
B --> C[Framework story value]
C --> D[Canvas element]
B -->|ready or error| A
B -->|cleanup callback| A
References: code/…/renderToCanvas.tsx• L69-137 code/…/render.ts• L53-121 code/…/render.ts• L45-110 code/…/render.ts• L44-70
Framework value mapping
Each renderer accepts the value that is natural for its UI technology. React mounts a component tree, Vue creates an app and maps slot arguments to slots, and Svelte mounts a preview wrapper that carries the story function and context. HTML and Web Components handle browser values directly, including strings, DOM nodes, document fragments, and Lit template results. code/…/renderToCanvas.tsx• L79-113 code/…/render.ts• L17-25 code/…/render.ts• L126-146 code/…/render.ts• L78-104 code/…/types.ts• L10-19 code/…/types.ts• L17-29
The result type is part of the renderer contract. It tells story authors and framework adapters what a story can return. The canvas lifecycle tells the preview how to display and remove it. code/…/types.ts• L17-20 code/…/types.ts• L17-29
References: code/…/types.ts• L8-12 code/…/types.ts• L26-37 code/…/types.ts• L5-18 code/…/render.ts• L12-42 code/…/render.ts• L17-41
State updates and remounts
Storybook changes args and globals without always replacing the story. Vue updates reactive state in the current app, Svelte mutates reactive preview props, React updates the component tree and uses a fresh story key when a full remount is needed, and browser renderers replace or reuse the current DOM value. Reset actions can require a full remount when a framework does not restore default props by itself. Svelte therefore treats a reset event for the current story as a remount request. code/…/render.ts• L57-76 code/…/render.ts• L20-32 code/…/render.ts• L66-101 code/…/renderToCanvas.tsx• L84-109
This split preserves useful component state during normal story updates while still allowing tests and story actions to request clean component instances. The renderer owns the rule for when an update is safe and when cleanup must happen first. A failed Svelte update does not prevent a later update from rendering the story again, and a Vue update can show the main canvas again after a failed mount. code/…/renderToCanvas.tsx• L84-109 code/…/render.ts• L57-76 code/…/render.test.ts• L191-231 code/…/render.ts• L66-109 code/…/render.test.ts• L39-74
References: code/…/renderToCanvas.tsx• L84-109 code/…/render.ts• L57-76 code/…/render.test.ts• L159-231 code/…/render.ts• L20-32 code/…/render.ts• L66-109 code/…/render.test.ts• L26-74 code/…/render.ts• L48-60 code/…/render.ts• L50-72
Framework-facing preview APIs
Renderer packages expose more than canvas mounting. Their public entry points provide renderer types, preview configuration, portable story helpers, and framework-aware story factories. These APIs let the same story annotations work in Storybook and in external test or composition flows.
| Surface | Purpose |
|---|---|
| Renderer types | Describe component inputs, story results, context, and optional mount behavior. |
| Preview configuration | Add renderer annotations for story rendering, docs, and type inference. |
| Portable story helpers | Apply project annotations and compose stories outside the full Storybook UI. |
| Entry preview modules | Supply the renderer name and runtime hooks consumed by the preview. |
React test integration
The React preview entry connects Storybook's test helpers to React's act scope. Its startup hook wraps timer advances and user events in act, pauses act warnings while asynchronous waits drain pending work, and restores the previous global state afterward. Nested events reuse the current act scope. Production or disabled-act paths call the callback directly. code/…/entry-preview.tsx• L54-97 code/…/act-compat.ts• L14-102
The wrapper returns the event callback's result and restores its state after failures. One failed or nested event therefore does not affect later events. code/…/act-compat.test.ts• L6-47
References: code/…/entry-preview.tsx• L54-115 code/…/act-compat.ts• L14-102 code/…/act-compat.test.ts• L6-47
Each renderer also exposes public types for Meta, StoryFn, StoryObj, decorators, loaders, story context, and project preview. Component-based renderers connect these types to component props. Simpler renderers use the shared argument shape. code/…/public-types.ts• L21-80 code/…/public-types.ts• L21-83 code/…/public-types.ts• L20-79 code/…/public-types.ts• L15-42 code/…/public-types.ts• L15-42 code/…/public-types.ts• L15-42
References: code/…/index.ts• L1-9 code/…/index.ts• L1-9 code/…/index.ts• L1-7 code/…/index.ts• L1-4 code/…/index.ts• L1-4 code/…/public-types.ts• L21-80 code/…/public-types.ts• L21-83 code/…/public-types.ts• L20-79 code/…/public-types.ts• L15-42 code/…/public-types.ts• L15-42
Typed story factories
React and Vue expose definePreview wrappers that add renderer annotations to the shared preview API. Their meta() and story() methods infer args from the component and preserve renderer-specific story types. This gives framework users a typed path from preview configuration to individual stories. code/…/preview.tsx• L33-82 code/…/preview.ts• L29-56
The typed preview also carries addon types into the renderer's story model. Framework code can add renderer or addon data without losing the link between component props, story args, decorators, and story results. code/…/preview.tsx• L85-126 code/…/preview.ts• L64-126
References: code/…/preview.tsx• L33-82 code/…/preview.tsx• L85-126 code/…/preview.ts• L29-56 code/…/preview.ts• L64-126
Portable stories
Portable stories are stories composed for use outside the normal Storybook preview page. Renderer packages apply their built-in annotations and combine them with project annotations so decorators, parameters, and other story behavior remain consistent in unit tests or other consumers. React also exposes composition helpers for one story or a full story module. code/…/portable-stories.tsx• L27-55 code/…/portable-stories.tsx• L77-158 code/…/portable-stories.ts• L14-41
The same project-annotation setup is available for HTML and Preact. Renderer defaults are installed before user annotations so the composed story uses the same rendering model as Storybook. code/…/portable-stories.ts• L14-41
References: code/…/portable-stories.tsx• L14-24 code/…/portable-stories.tsx• L46-75 code/…/portable-stories.tsx• L106-158 code/…/portable-stories.ts• L14-41 code/…/portable-stories.ts• L14-41
Documentation source previews
Svelte and Vue preview entries connect story docs to source code that reflects the current story args. In the normal client path, a renderer decorator creates source text from the mounted story. Svelte CSF stories use their transformed raw story source instead of this generic decorator. When the docgen server is enabled, the entry disables the client decorator and gives story docs a hole printer so the server-generated template can receive updated values. This avoids duplicate source generation. code/…/entry-preview-docs.ts• L7-14 code/…/sourceDecorator.ts• L155-186 code/…/entry-preview-docs.ts• L4-9
The renderer-specific source generators preserve the shape of each technology. Svelte prints component props and slots. Vue prints template bindings, slots, and script values for complex args. Both skip source generation when a story supplies fixed source or is not an args story, unless dynamic source is explicitly requested. code/…/sourceDecorator.ts• L15-27 code/…/sourceDecorator.ts• L87-114 code/…/sourceDecorator.ts• L42-56 code/…/sourceDecorator.ts• L64-107 code/…/sourceDecorator.ts• L116-136
References: code/…/entry-preview-docs.ts• L1-14 code/…/sourceDecorator.ts• L15-27 code/…/sourceDecorator.ts• L155-186 code/…/entry-preview-docs.ts• L1-9 code/…/sourceDecorator.ts• L42-136
Renderer family coverage
Renderer packages share one preview contract but target different story result models. The package set covers component frameworks, browser-native output, and server-oriented output. Framework packages choose among these renderers and add project-specific presets around them.
| Renderer family | Story result model | Main preview concern |
|---|---|---|
| React | React element and component tree | React roots, error boundaries, strict mode, and test act behavior. |
| Vue 3 | Vue component or functional component | App setup, reactive args and globals, slots, and app teardown. |
| Svelte | Svelte component with props | Reactive story props, full remounts for reset behavior, and component metadata for docs. |
| Preact | Preact component model | Portable story and preview integration for Preact projects. |
| HTML | String or DOM node | Browser insertion and simulated page or DOM load events. |
| Web Components | Custom element, DOM value, or Lit template | Custom element rendering and Lit template updates. |
| Server | Server-oriented story result | A renderer entry point for server framework integrations. |
The package exports define the boundary that framework integrations consume. Every listed renderer provides a public package entry, a preview entry, and a preset entry; packages add docs, arg-types, server-component, or typed preview entries only where their framework needs them. Svelte also exposes story-file tooling for its Svelte CSF format. React and Web Components expose dedicated arg-types entries, and React also exposes a server-component entry. code/…/package.json• L23-45 code/…/package.json• L27-46 code/…/package.json• L26-75 code/…/package.json• L27-36 code/…/package.json• L29-45
References: code/…/package.json• L23-45 code/…/package.json• L27-46 code/…/package.json• L26-75 code/…/package.json• L27-36 code/…/package.json• L27-36 code/…/package.json• L29-45 code/…/package.json• L26-34
Svelte CSF stories
Svelte CSF stories let authors declare Storybook metadata and stories in Svelte markup. The renderer supports both defineMeta() and the preview factory form, turns that source into index entries for discovery, and creates normal CSF story objects for the preview. It keeps story markup, args, inheritance, snippets, asChild content, and play behavior connected.
The Svelte story path has three stages:
- The indexer reads the Svelte file and publishes one story entry for each declared story.
- The compiler combines the Svelte source and compiled output to produce a CSF module with source mapping.
- The runtime collects story declarations, resolves inherited content and annotations, and renders each story through a shared story renderer.
This diagram shows how Svelte CSF source becomes discoverable and mountable stories.
flowchart LR
A[Svelte CSF file] --> B[Indexer]
A --> C[CSF transform]
C --> D[Runtime story objects]
D --> E[Svelte story renderer]
B --> F[Story index]
F --> D
The indexer recognizes supported metadata declarations and story components. Story names can produce valid export names, while an explicit export name resolves naming collisions. Story inheritance carries tags and content from the named parent. A story can use a template or children, but not both with asChild in the same declaration. The runtime disables saving from the controls panel for .stories.svelte files because that source form is not supported by the save flow. Errors while collecting stories are logged so discovery can report the problem without making the renderer fail silently. code/…/parser.ts• L76-304 code/…/identifier-utils.ts• L3-31 code/…/create-runtime-stories.ts• L17-115
The compiler reads both the original Svelte AST and the compiled JavaScript AST. It adds the runtime story collection, metadata, source text, named exports, and source maps to the compiled module. This keeps story locations and docs source tied to the author's Svelte file. code/…/transform.ts• L1-63 code/…/index.test.ts• L20-119
The runtime mounts the stories file once to collect each <Story> declaration. It then builds the final story objects by finding inherited content, templates, asChild settings, and play functions along the parent chain. A story keeps the arg source that owns each value. If that value changes inside the Svelte story, the runtime sends the changed arg back through Storybook's update channel so the preview stays in sync. Plain objects and arrays are copied before comparison, which lets nested reactive state trigger an update without sending the same value again after a remount or hot update. code/…/create-runtime-stories.ts• L17-123 code/…/sync-story-args.ts• L16-62 code/…/types.ts• L112-144
References: code/…/parser.ts• L76-304 code/…/identifier-utils.ts• L3-31 code/…/transform.ts• L1-63 code/…/index.test.ts• L20-119 code/…/create-runtime-stories.ts• L17-123 code/…/component-helpers.ts• L1-16 code/…/sync-story-args.ts• L16-62 code/…/types.ts• L32-144 code/…/example.stories.svelte• L16-56
React component documentation
The React renderer supplies component metadata for the docs system through a lazy provider that runs in a worker. It creates the metadata manager only when an eligible request arrives, keeps it warm across components, and falls back to the rest of the docs provider chain when TypeScript is not available.
The React docs path has two sources of argument metadata. The docgen server inspects a component file directly, which supports requests outside a story file. Builder docgen uses the configured React docgen mode and checks the matching optional packages before it runs. A TypeScript mode falls back to react-docgen when the TypeScript compiler API is not usable.
Component lookup follows re-export paths and matches the result to the requested component export. The docs path describes component names, text, props, defaults, and argument types. It supports wrapped components such as React.memo, subcomponents, and JavaScript components with JSDoc props. React-owned ref and key values do not become user controls. Source defaults keep their literal or expression meaning in the docs data. code/…/getComponentImports.ts• L62-79 code/…/resolveComponents.ts• L127-203 code/…/buildDocgen.test.ts• L43-164 code/…/buildDocgen.test.ts• L166-397
React component manifests also create story source that follows the story's render shape. They can synthesize JSX from args or preserve a resolvable render function. The resulting source can keep imported values and report values that static analysis cannot resolve, while a template allows docs to replace changed args without changing unrelated code. code/…/resolveComponents.ts• L205-262 code/…/generateCodeSnippet.test.tsx• L829-1001 code/…/generateCodeSnippet.test.tsx• L1166-1515
The React preset enables the worker-backed provider only when the project can load TypeScript. It keeps the renderer's preview entries and React package resolution aligned with the project's installed React and React DOM versions, so docs and preview code use the same runtime. code/…/preset.ts• L36-83 code/…/preset.ts• L85-129
References: code/…/preset.ts• L30-50 code/…/preset.ts• L131-205 code/…/builder-docgen.ts• L11-99 code/…/getComponentImports.ts• L62-319 code/…/resolveComponents.ts• L82-262 code/…/types.ts• L5-19 code/…/generateCodeSnippet.test.tsx• L829-1515 code/…/buildDocgen.ts• L34-157 code/…/buildDocgen.test.ts• L43-397
Svelte component documentation
Svelte renderer packages provide component metadata for the docs system. The provider starts only when the project can load TypeScript. It reads eligible story components and subcomponents to supply names, descriptions, props, events, slots, defaults, and argument types.
Svelte docs also include an API description with typed sections for props, events, and slots. It preserves useful defaults and binding information while omitting details that are too large to list, such as inherited browser attribute types. code/…/api-description.ts• L7-62 code/…/api-description.ts• L90-109
The docs path resolves the component named by a story or Svelte defineMeta() declaration through imports and re-exports. It then combines the component's source and metadata into one docs payload. A missing or invalid primary component can stop that payload, while a subcomponent that cannot resolve is skipped so it does not hide the main component's docs. code/…/resolve-component.ts• L67-137 code/…/resolve-component.ts• L139-189 code/…/build-docgen.ts• L28-87
The provider runs its metadata work in a worker and keeps a project view for each Svelte project. File watching keeps that view current as components and type files change. If the docgen engine cannot load, the provider warns and lets another docs path handle the request. code/…/docgen-worker.ts• L7-34 code/…/svelte-project-manager.ts• L28-175
References: code/…/docgen-worker.ts• L7-34 code/…/preset.ts• L7-49 code/…/build-docgen.ts• L28-87 code/…/resolve-component.ts• L32-189 code/…/api-description.ts• L7-187 code/…/svelte-project-manager.ts• L28-175
Vue component documentation
The Vue renderer supplies component metadata for the docs system through a worker-backed provider. It reads the story's component declaration, follows imports and re-exports to the declaring component, and turns Vue metadata into descriptions, argument types, and API details.
Vue component resolution accepts an imported component, a namespace property, or a chain that the shared resolver can follow. The resolver returns a clear reason when the story has no component, names no import, uses an unreadable expression, or names an export that does not exist. code/…/resolve-component.ts• L16-48
Declared subcomponents use the same extraction path as the primary component. A failure for one child becomes an error on that child instead of preventing documentation for the main component or its other children. The story-docs path also resolves static args and follows spreads, bindings, slots, and complex values so its source reflects the story's rendered result. code/…/build-docgen.ts• L123-182 code/…/build-docgen.ts• L185-239 code/…/build-docgen.ts• L324-361 code/…/build-story-docs.test.ts• L111-276 code/…/build-story-docs.test.ts• L282-447
References: code/…/docgen-worker.ts• L18-53 code/…/resolve-component.ts• L1-48 code/…/build-docgen.ts• L61-182 code/…/build-docgen.ts• L185-361 code/…/build-story-docs.test.ts• L111-447 code/…/preset.ts• L7-15
Browser-native renderers
HTML and Web Components use the browser as the main rendering host instead of creating a framework app. HTML stories return strings or DOM nodes. Web Components stories identify a custom element by tag name and can return DOM values or Lit templates. Both renderers translate unsupported story results into a visible preview error. code/…/render.ts• L12-70 code/…/render.ts• L17-81
Web Components also links component metadata to framework-facing configuration. The preferred path uses a Custom Elements Manifest through framework options and server-side docs generation. Older runtime manifest helpers remain only as deprecated compatibility APIs. code/…/types.ts• L5-15 code/…/framework-api.ts• L5-50
Web Components story docs turn a story's markup or render function into source that can show the current args. The snippet builder replaces reads of those args with printable values and marks the replacements as holes, so the docs view can update source when controls change. It keeps the story's code valid when a value needs grouping or when a render function uses a block body. code/…/render-snippet.ts• L14-59
The builder supports direct arg reads and simple destructured parameters. If the render code binds or uses a shape that it cannot safely trace, it can return static snippet text without a live template. This favors readable source over a guessed update that could change the story's meaning. code/…/render-snippet.ts• L61-120 code/…/render-snippet.ts• L204-234
The Web Components docs provider prefers configured Custom Elements Manifest files. When no manifest is available, it can generate declarations from source when TypeScript and the source generator are ready. A source-generation failure does not remove a usable manifest path, and a manifest can enable docs generation without TypeScript. code/…/docgen-worker.ts• L13-47 code/…/preset.ts• L9-21
References: code/…/render.ts• L44-70 code/…/render.ts• L43-81 code/…/types.ts• L5-29 code/…/framework-api.ts• L5-50 code/…/render-snippet.ts• L14-234 code/…/docgen-worker.ts• L13-47
Framework error handling
Renderers turn framework failures into preview state that Storybook can display. React uses an error boundary around the story. Vue routes app errors to the preview and preserves errors from interaction playback. Svelte lets a story-function error reject the render operation, then accepts a later update. Browser renderers report invalid story results with a focused error message. code/…/renderToCanvas.tsx• L13-43 code/…/render.ts• L99-114 code/…/render.test.ts• L39-74 code/…/render.ts• L61-69
This boundary keeps framework-specific error rules inside the renderer. The preview runtime can then use one lifecycle shape for ready and failed stories even though UI systems report errors in different ways. Vue can also restore the main canvas after a later update fixes a component that failed during mount. code/…/renderToCanvas.tsx• L13-43 code/…/renderToCanvas.tsx• L100-109 code/…/render.ts• L99-121 code/…/render.test.ts• L159-231 code/…/render.ts• L61-69 code/…/render.ts• L73-81
References: code/…/renderToCanvas.tsx• L13-43 code/…/renderToCanvas.tsx• L100-109 code/…/render.ts• L99-121 code/…/render.test.ts• L159-231 code/…/render.ts• L78-105 code/…/render.test.ts• L26-74 code/…/render.ts• L61-69 code/…/render.ts• L73-81
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the renderer name in the preview entry, renderer type, framework selection, and renderer registry aligned.
- Keep the story result type,
renderbehavior, andrenderToCanvasaccepted values aligned for each renderer. - Preserve the cleanup contract when changing mount, update, or force-remount behavior.
- Update portable story defaults when renderer annotations or preview setup change.
- Keep each renderer's root, preview, docs, arg-types, internal, typed preview, and preset export names aligned with their consumers when package boundaries change.
- Preserve React act environment restoration, nested event scope, callback results, and lazy test-helper loading when changing preview test integration.
- Preserve docgen provider enablement rules: React, Svelte, and Vue need usable TypeScript, while Web Components can use a Custom Elements Manifest without it.
- Keep React docgen provider selection, builder package checks, component-file argTypes extraction, and docs argTypes results aligned.
- Keep React component docgen defaults, framework-owned attribute filtering, wrapped component support, and subcomponent argTypes aligned.
- Keep React component export matching, re-export traversal, and source-path resolution aligned so docs identify the requested component.
- Keep React component discovery, import references, docgen targets, JSX depth, and generated snippet imports aligned when component manifest resolution changes.
- Preserve React snippet fallback rules: an unresolved render must not silently use a different meta render, and unresolved args must stay visible as warnings.
- Keep Svelte docgen payloads, component metadata, API descriptions, and docs argTypes aligned when changing Svelte component analysis.
- Preserve Svelte project refresh behavior for changed, created, deleted, and newly requested component or type files.
- Keep Svelte CSF indexing, source transformation, factory metadata, story inheritance, identifier rules, runtime story rendering, and arg synchronization aligned.
- Keep Svelte CSF import detection, supported meta forms, type-call handling, and
Storyname extraction aligned. - Keep Svelte source-AST and compiled-AST analysis aligned so generated CSF exports and source maps point to the right stories.
- Keep Svelte arg ownership and snapshots aligned with
UPDATE_STORY_ARGSso inherited args do not overwrite values owned by a child story. - Keep the Svelte docgen worker's optional startup and warning behavior aligned with the renderer's docs support.
- Keep Vue component resolution, primary metadata, and per-subcomponent error handling aligned when changing Vue docgen payloads.
- Keep Vue story-source resolution aligned with the runtime result for spreads, bindings, slots, and values that controls can add or change.
- Keep the Svelte and Vue docs preview entries mutually exclusive between client source decorators and server hole printing.
- Keep Web Components render snippet tracing, value printing, and live template holes aligned when story render syntax changes.
- Preserve Web Components manifest-first resolution and the fallback from source generation to other docs providers.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A story returns a value outside the renderer's result type. | The canvas cannot mount the story and shows a render error. | Keep story return types and renderer checks aligned. |
| A renderer updates args without preserving its reactive or mounted instance. | Controls or globals stop updating, or component state resets unexpectedly. | Use the renderer's update path for normal changes and reserve remounts for fresh state. |
| Cleanup does not unmount the current framework instance. | Old story state or DOM remains in the canvas after navigation. | Return and run renderer-specific teardown from renderToCanvas. |
| A framework integration selects the wrong renderer name. | The preview loads incompatible story annotations or mount logic. | Treat SupportedRenderer, preview parameters, and framework package selection as one contract. |
| A renderer package export is removed or renamed without updating its framework or builder consumer. | The selected preview, docs path, or preset cannot load even though the renderer code is present. | Keep package exports and the consumers that import them aligned. |
A Svelte CSF file uses an unimported preview binding, mixes meta styles, or uses an invalid story combination. | Its stories are missing from the index and the parser reports a file-specific error. | Use one supported meta form and keep its import, factory chain, and story markup aligned with the indexer rules. |
A Svelte story has no usable name or exportName, or two stories resolve to the same export. | The compiler cannot produce stable named story exports. | Give every story a valid identifier and use an explicit unique exportName when derived names collide. |
| Svelte source and compiled output do not describe the same story nodes. | Generated CSF exports or source maps point to the wrong story. | Keep source-AST and compiled-AST analysis in sync in the transform. |
| A Svelte story mutates a nested arg without a stable snapshot or sends an arg owned by an inherited story. | Controls show stale values or a child update overwrites the wrong story's value. | Preserve arg ownership, deep snapshots, and per-story sent-value tracking before emitting UPDATE_STORY_ARGS. |
React event helpers nest act scopes or fail to restore the act environment after an error. | Interaction work can produce warnings or affect later events. | Preserve the event wrapper's single-scope and restoration contract. |
| React, Svelte, or Vue docgen starts without a usable TypeScript setup. | Server-side component metadata is unavailable and another docs path must handle the request. | Keep provider enablement tied to TypeScript readiness. |
| React builder docgen selects a mode whose optional packages are missing. | Builder argTypes inference is disabled or reports a package setup error. | Check the selected mode's package set and use the documented fallback when TypeScript is unusable. |
| A React component is hidden behind an unreadable, unsupported, or too-deep re-export path. | Docs cannot identify the component and return a detailed extraction error. | Resolve to source files and keep re-export chains within the supported depth. |
| A React story's component discovery and docgen target disagree about the import or export. | Docs may show the wrong component metadata or fail to create the imports needed by its source. | Keep the story import reference separate from the declaring target while matching both to the requested export. |
| A React render or arg expression cannot be resolved and the snippet generator drops it without a warning. | Story docs show incomplete source that looks valid but does not describe the story. | Preserve unresolved markers and use the safe fallback source path. |
| A Vue story does not expose a component that the resolver can follow. | The main component or a child receives a focused docs error. | Import the component into the story and use a supported meta.component reference. |
| Web Components source generation fails while no manifest is configured. | Component metadata is unavailable to the docs provider. | Provide a valid Custom Elements Manifest or keep the TypeScript source-generation path loadable. |
| Web Components metadata uses the deprecated runtime path. | Component docs depend on a compatibility API that is planned for removal. | Configure customElementsManifest and server-side docs generation. |
| A Svelte or Vue docs entry enables client source decoration while the docgen server also supplies the story template. | Source output can be generated twice or controls can update the wrong source path. | Use the client decorator only without the server and use the server hole printer when the server is enabled. |
| A Web Components render function uses a parameter or binding shape that snippet tracing cannot follow. | Docs show static source without a live arg template. | Keep render arg reads simple when live source updates are required. |
| A Svelte component or imported type file changes without refreshing its project view. | Docs show old props or omit a newly available component. | Preserve file-change handling and the freshness check used by the Svelte docgen manager. |
Key files
| File | Why to read it |
|---|---|
| code/…/renderers.ts | Defines the shared names used to select renderer families. |
| code/…/renderToCanvas.tsx | Shows the component mount, error, remount, and cleanup lifecycle for React. |
| code/…/entry-preview.tsx | Shows React preview hooks that connect Storybook test helpers to act. |
| code/…/act-compat.ts | Shows React act environment and event-scope behavior. |
| code/…/preset.ts | Shows React preview entry selection, docs provider enablement, argTypes extraction, and build-tool integration. |
| code/…/buildDocgen.ts | Shows how React component metadata becomes the common docs payload. |
| code/…/buildDocgen.test.ts | Shows the React docgen payload contract for defaults, subcomponents, wrapped components, and JavaScript props. |
| code/…/getComponentImports.ts | Shows how story components become import references and docgen inputs. |
| code/…/resolveComponents.ts | Shows component matching, re-export targets, subcomponents, and story source extraction. |
| code/…/generateCodeSnippet.test.tsx | Shows how React story args and render functions become readable source and live templates. |
| code/…/public-types.ts | Shows how React component props flow into public story types. |
| code/…/portable-stories.tsx | Shows how renderer defaults and project annotations compose for portable stories. |
| code/…/preview.tsx | Shows renderer-specific typed preview and story factory APIs. |
| code/…/render.ts | Shows app setup, reactive story updates, slot mapping, error routing, and teardown for Vue 3. |
| code/…/render.test.ts | Shows the Vue contracts for reactive updates, slots, error reporting, and recovery after a failed mount. |
| code/…/entry-preview-docs.ts | Shows the switch between client source decoration and server story-docs hole printing. |
| code/…/sourceDecorator.ts | Shows how Vue props, slots, and complex values become story source. |
| code/…/resolve-component.ts | Shows how Vue story references resolve to component files and exports. |
| code/…/build-docgen.ts | Shows how Vue story declarations become primary and subcomponent docs data. |
| code/…/build-story-docs.test.ts | Shows the Vue story-source contract for static args, bindings, slots, and live changes. |
| code/…/render.ts | Shows Svelte's reactive preview wrapper and reset-driven remount behavior. |
| code/…/render.test.ts | Shows Svelte's missing-component error and recovery contract after a failed args update. |
| code/…/entry-preview-docs.ts | Shows the switch between client source decoration and server story-docs hole printing. |
| code/…/sourceDecorator.ts | Shows how Svelte args become component source for story docs and why Svelte CSF uses its own source path. |
| code/…/parser.ts | Shows how Svelte CSF metadata, factories, identifiers, inheritance, and story declarations enter indexing. |
| code/…/transform.ts | Shows how Svelte CSF source and compiled output become a mapped CSF module. |
| code/…/create-runtime-stories.ts | Shows how declared Svelte stories become runtime story objects and preserve inherited behavior. |
| code/…/sync-story-args.ts | Shows how reactive story args return to Storybook without duplicate updates. |
| code/…/types.ts | Shows the Svelte CSF story, inheritance, and arg-source contracts. |
| code/…/example.stories.svelte | Shows the supported Svelte CSF story forms, templates, children, and story metadata. |
| code/…/docgen-worker.ts | Shows the worker-backed Svelte metadata provider and its startup behavior. |
| code/…/resolve-component.ts | Shows how Svelte stories and defineMeta() references resolve to components. |
| code/…/build-docgen.ts | Shows how Svelte component metadata becomes the common docs payload. |
| code/…/api-description.ts | Shows how Svelte metadata becomes a props, events, and slots API description. |
| code/…/render.ts | Shows the browser-native string and DOM node rendering path. |
| code/…/render.ts | Shows custom element and Lit template rendering in the canvas. |
| code/…/render-snippet.ts | Shows how Web Components render code becomes a value-filled snippet and live template. |
| code/…/preset.ts | Shows manifest-aware docs provider enablement and Web Components preview entries. |
| code/…/docgen-worker.ts | Shows manifest-first metadata resolution and source-generation fallback. |
| code/…/framework-api.ts | Shows the compatibility boundary for custom element metadata. |
| code/…/package.json | Shows the public preview, preset, docs, and internal export boundaries for renderer families. |