Default link handling in SvelteKit Storybook
By default, clicking an <a href="..." /> element in Storybook logs an action to the Actions panel. This can be overridden by assigning an object to parameters.sveltekit_experimental.hrefs.
Storybook · Setup · all subjects
configuration
333 notes in this subject, read out of this brain and free to use. This is page 5 of 6.
SvelteKit framework parameter: forms
Parameter name: forms. Type: { enhance: () => void }. Provides mocks for the $app/forms module. The forms.enhance property is a callback that will be called when a form with use:enhance is submitted.
SvelteKit framework parameter: hrefs
Parameter name: hrefs. Type: Record<[path: string], (to: string, event: MouseEvent) => void | { callback: (to: string, event: MouseEvent) => void, asRegex?: boolean }>. If an <a /> tag href matches one or more defined links (treated as regex if asRegex is true), the corresponding callback will be called. If no matching hrefs are defined, an action is logged to the Actions panel.
SvelteKit framework parameter: navigation
Parameter name: navigation. Type: See SvelteKit docs. Provides mocks for the $app/navigation module. Sub-properties include goto, pushState, replaceState, invalidate, invalidateAll, and afterNavigate, each being callbacks that correspond to SvelteKit navigation functions. If not provided, actions are logged to the Actions panel.
SvelteKit framework parameter: stores
Parameter name: stores. Type: See SvelteKit docs. Provides mocks for the $app/stores module. Sub-properties include navigating (partial version of navigating store), page (partial version of page store), and updated (boolean representing the value of updated store).
SvelteKit framework parameter: state
Parameter name: state. Type: See SvelteKit docs. Provides mocks for the $app/state module. Sub-properties include navigating (partial version of navigating store), page (partial version of page store), and updated (object with current boolean property, with check() being a no-op).
SvelteKit framework options: builder
Option name: builder. Type: Record<string, any>. Configure options for the framework's builder. For SvelteKit, available options can be found in the Vite builder docs.
SvelteKit framework options: docgen
Option name: docgen. Type: boolean. Default: true. Enables or disables automatic documentation generation for component properties. When disabled, Storybook will skip the docgen processing step during build, which can improve build performance. See svelte-framework-options-docgen.md for example configuration.
When to disable docgen in SvelteKit
Disabling docgen can improve build performance for large projects, but argTypes won't be inferred automatically. This will prevent features like Controls and docs from working as expected. To use those features with docgen disabled, manually define argTypes.
Framework options for Vue 3 Vite
The framework options object for @storybook/vue3-vite includes: builder (Record<string, any>) - Configure options for the framework's builder with available options in the Vite builder docs; docgen ('vue-docgen-api' | 'vue-component-meta' | boolean, default 'vue-docgen-api', since 8.0) - Choose which docgen tool to use when generating controls. Set to false to disable docgen processing entirely for improved build performance.
Run Storybook for Vue Vite
To run Storybook for a Vue Vite project, use the command referenced in code snippets path 'storybook-run-dev.md'. To build Storybook, use the command from 'build-storybook-production-mode.md'. The default output directory is 'storybook-static', configurable via outputDir.
Extend Vue application in Storybook
Storybook provides a `setup` function exported from '@storybook/vue3-vite' that receives your Storybook instance as a callback. Use this to configure global custom components, directives, extensions, or other application methods in the ./storybook/preview.ts file. Example: import { setup } from '@storybook/vue3-vite'; setup((app) => { app.use(MyPlugin); app.component('my-component', MyComponent); app.mixin({ // My mixin }); });
Disable docgen for performance
Set docgen to false in framework options to disable docgen processing and improve build performance. Example: import type { StorybookConfig } from '@storybook/vue3-vite'; const config: StorybookConfig = { framework: { name: '@storybook/vue3-vite', options: { docgen: false, // Disable docgen for better performance }, }, }; export default config; Note: Disabling docgen prevents argTypes from being inferred automatically, which breaks Controls and autodocs features unless you manually define argTypes.
vue-component-meta availability and status
vue-component-meta is only available in Storybook ≥ 8. It is currently opt-in but will become the default in a future version of Storybook.
Enable vue-component-meta in Storybook configuration
To use vue-component-meta, configure it in .storybook/main.ts like this: import type { StorybookConfig } from '@storybook/vue3-vite'; const config: StorybookConfig = { framework: { name: '@storybook/vue3-vite', options: { docgen: 'vue-component-meta', }, }, }; export default config;
vue-component-meta supported component types
vue-component-meta supports all types of Vue components including SFC, functional, composition API, and options API components from .vue, .ts, .tsx, .js, and .jsx files. It also supports both default and named component exports.
Document Vue component props with JSDoc
To describe props in vue-component-meta, use JSDoc comments in your component's props definition. Example: <script setup lang="ts"> interface MyComponentProps { /** The name of the user */ name: string; /** * The category of the component * * @since 8.0.0 */ category?: string; } withDefaults(defineProps<MyComponentProps>(), { category: 'Uncategorized', }); </script> This generates controls in Storybook with the documented prop descriptions.
Extract event types in vue-component-meta
To provide types for emitted events in vue-component-meta, use TypeScript types with JSDoc comments in your component's defineEmits call. Example: <script setup lang="ts"> type MyChangeEvent = 'change'; interface MyEvents { /** Fired when item is changed */ (event: MyChangeEvent, item?: Item): void; /** Fired when item is deleted */ (event: 'delete', id: string): void; /** Fired when item is upserted into list */ (e: 'upsert', id: string): void; } const emit = defineEmits<MyEvents>(); </script> This generates event controls in Storybook.
Extract slot types in vue-component-meta
Slot types are automatically extracted from component definitions. Use defineSlots with JSDoc comments to describe each slot. Example: defineSlots<{ /** Example description for default */ default(props: { num: number }): any; /** Example description for named */ named(props: { str: string }): any; /** Example description for no-bind */ noBind(props: {}): any; /** Example description for vbind */ vbind(props: { num: number; str: string }): any; }>(); This generates slot controls in Storybook's Controls panel.
Extract exposed properties and methods in vue-component-meta
Properties and methods exposed by your component are automatically extracted and displayed in the Controls panel. Example: <script setup lang="ts"> import { ref } from 'vue'; const label = ref('Button'); const count = ref(100); defineExpose({ /** A label string */ label, /** A count number */ count, }); </script>
Override vue-component-meta tsconfig for references
If your project uses tsconfig references (e.g., tsconfig.app.json, tsconfig.node.json), update .storybook/main.ts like this: import type { StorybookConfig } from '@storybook/vue3-vite'; const config: StorybookConfig = { framework: { name: '@storybook/vue3-vite', options: { docgen: { plugin: 'vue-component-meta', tsconfig: 'tsconfig.app.json', }, }, }, }; export default config; This prevents missing component types/descriptions or unresolvable import aliases.
TanStack React framework options configuration
You can pass an options object to @storybook/tanstack-react for additional configuration. The available options are: builder (type: Record<string, any>) - Configure options for the framework's builder. Available options can be found in the Vite builder docs.
Automatic memory-backed router in TanStack React framework
Storybook for TanStack React automatically wraps each story in a memory-backed TanStack Router using @storybook/builder-vite. This provides working router context in Storybook without booting the full application shell.
Supply TanStack Route via parameters.tanstack.router.route
To render a TanStack Route object as the story component, supply it through parameters.tanstack.router.route. Storybook extracts the route's React component from the route and keeps the route available for typed router configuration.
Dynamic route params with params and routeOverrides in TanStack React
Supply params alongside routeOverrides under parameters.tanstack.router to handle dynamic params (e.g., /$id). The params object is interpolated into the URL, and routeOverrides lets you stub the loader without touching the original route.
Nested routes automatically include parent layout routes in TanStack React
When route is a file route connected to your app's route tree, Storybook automatically includes parent layout routes so the story renders inside the same nested hierarchy as the real app. You can also pass the routeTree export from routeTree.gen.ts directly.
Provide routing context for non-Route components in TanStack React
If a story renders a regular React component instead of a route object, you can still provide routing context through parameters.tanstack.router. This is useful when your component reads from hooks such as useRouterState, useSearch, useParams, or useLoaderData, but you do not want to make the route itself the story component.
Search params and URL fragments in TanStack React stories
Use query for search params (e.g., ?tab=details&page=2) and path for a URL fragment (e.g., #section-name) under parameters.tanstack.router.
Override route options per story with routeOverrides in TanStack React
When a route has a loader or beforeLoad that calls real APIs, you can override those options per story without modifying the original route object. Pass routeOverrides under parameters.tanstack.router. Each key is a route ID and the value can override loader, beforeLoad, validateSearch, loaderDeps, and context. Use '__root__' as the key to target the root route.
Automatic TanStack Router and Start mocking in framework
Storybook's TanStack React framework automatically redirects @tanstack/react-router imports to a Storybook-compatible mock layer. That mock re-exports TanStack Router APIs, keeps hooks such as useNavigate(), useSearch(), and useParams() available in stories, and wires navigation attempts into Storybook spies. For TanStack Start apps, the integration also stubs TanStack Start server and runtime entry points.
Mock TanStack Start server functions per story
If your component imports a TanStack Start server function, Storybook turns that createServerFn().handler(...) result into a mock function. You can override it per story with standard mock APIs.
Framework-level mocks for TanStack modules automatic
The TanStack React preset automatically intercepts @tanstack/react-start, @tanstack/react-start/server, @tanstack/start-storage-context, and related TanStack modules. It also replaces createServerFn() handlers with mock functions. No manual configuration is needed for these.
Mock app-level server modules in TanStack React with __mocks__ file
When routes import app-specific server code (e.g. ~/db/client, ~/auth/index.server), use Storybook's mocking with a __mocks__ file to prevent the real module and its Node.js dependencies from loading in the browser. Create the __mocks__ file next to the real module using only import type so no server packages are pulled in.
Register server module mocks in .storybook/preview.ts
To mock app-level server modules in TanStack React, register the mock in .storybook/preview.ts using Storybook's mocking API before creating the __mocks__ file next to the real module.
Why use __mocks__ instead of automocking for server modules
Storybook's automocking replaces functions but still evaluates the original module and its imports. For modules that import postgres, pg, or other Node.js-only packages, the original module must never be evaluated because it would crash the browser. A __mocks__ file is the only approach that completely prevents evaluation of the original module and its dependency chain.
Identify server-only modules by error stack trace in TanStack React
When troubleshooting server-only module errors in TanStack React, walk the error stack trace from top to bottom and stop at the first import you wrote yourself. Then add a __mocks__ file for it. The Node.js dependency is the smoking gun; mock the closest module to it that you control.
TanStack Query setup with TanStack React framework
To use TanStack Query with TanStack React framework, create a single QueryClient in your preview file, clear it between stories via beforeEach, and share the same instance through both parameters.tanstack.router.context and a QueryClientProvider decorator. This keeps the router context and React provider pointed at the same QueryClient.
Seed query data per story in TanStack React with Query
In individual stories using TanStack Query with TanStack React framework, use beforeEach to call setQueryData on the shared QueryClient before the component renders. Access it from parameters.tanstack.router.context.
Per-story QueryClient in TanStack React with Query
You can create a separate QueryClient for each story when you need stronger isolation, such as rendering several stories with the same query keys on one Docs page. The tradeoff is that you must make the per-story client available to both the router context and the QueryClientProvider for that story, and you must explicitly clean up timers, subscriptions, and cached data owned by each client.
When to use tanstack-react vs react-vite framework
Use @storybook/tanstack-react when your components rely on TanStack Router or TanStack Start APIs and you want Storybook to provide router context, typed route parameters, automatic router mocking, and mocked TanStack Start server-function behavior. Use @storybook/react-vite when your app is a standard React and Vite project without TanStack Router.
Provide React context providers to all stories in TanStack React
To provide React context providers (e.g. theme, toast, auth) to all stories in TanStack React, add project-level decorators. You can also add component-level decorators to apply providers to all stories for a specific component, or story-level decorators to apply providers to a single story.
React Server Components not supported in TanStack React
@storybook/tanstack-react does not support React Server Components because it runs stories in the browser using a memory-backed router. React Server Components require a server runtime. If your component is a Server Component, extract the client-side parts into a Client Component and write stories for that instead.
Story fails to render with module export error in TanStack React
If a story fails to render with an error about modules not providing a default export, this usually means a server-only module is being imported in the browser. Check the error stack trace to find the module and add a Storybook mock for it as described in Handling server-only dependencies.
Export module @storybook/tanstack-react/react-router
The package exports @storybook/tanstack-react/react-router which contains TanStack Router-compatible mock implementations used by the framework to provide router behavior in stories. Import from this module when you need direct access to the mock APIs, for example to assert against navigation spies in tests.
Export module @storybook/tanstack-react/start
The package exports @storybook/tanstack-react/start which contains TanStack Start-compatible mock implementations, including a mocked createServerFn() implementation. Import from this module when a story or test needs to interact directly with the Start mock layer.
TanStack router parameters namespace in framework
The TanStack React framework contributes parameters under the tanstack.router namespace. These parameters configure router behavior, context, route options, and path/query settings for stories.
Parameter context in tanstack.router for router context values
The context parameter under tanstack.router accepts a static object or a factory function that receives the story context. Type: Record<string, unknown> | (({ storyContext }) => Record<string, unknown>). Router context values injected into the story router. The factory runs before the router's initial load and outside React rendering, so its values are available to route loader and beforeLoad.
Parameter params in tanstack.router for route params
The params parameter under tanstack.router interpolates route params into the current path. Type: ResolveParams<Path>. When route is a typed file route, the type is constrained to the param names declared in that route's path (for example, { id: string } for /$id).
Parameter path in tanstack.router for initial URL path
The path parameter under tanstack.router sets the initial URL path for the story router. Type: string.
Parameter query in tanstack.router for search params
The query parameter under tanstack.router appends search params to the initial URL. Type: Record<string, unknown>.
Parameter route in tanstack.router for route instance
The route parameter under tanstack.router supplies a route instance directly or creates a temporary story route from route options. Type: AnyRoute | route options object. Storybook extracts the route's React component automatically from the route.
Parameter routeOverrides in tanstack.router for per-route overrides
The routeOverrides parameter under tanstack.router provides per-route overrides keyed by route ID, applied to the story's route and root route. Type: Partial<Record<string, RouteOverrideOptions>>. Use '__root__' to target the root route. Each entry can override loader, beforeLoad, validateSearch, loaderDeps, and context.
Parameter useRouterContext in tanstack.router for React hook context
The useRouterContext parameter under tanstack.router computes the router context during rendering as a React hook. Type: ({ storyContext }) => RouterContext. Use this when the value can only be read from a React provider rendered around the story (for example, a QueryClient obtained from useQueryClient()). This runs during rendering after the router's initial load, so its values reach rendered components but not the initial loader or beforeLoad.
Route options supported in tanstack.router.route parameter
When route is supplied as a plain object in tanstack.router.route, it may also include TanStack route options such as head (method), search (guide), and params.parse (method).
Run Storybook development server
To run Storybook for a particular project, use the storybook run dev command.
Build Storybook production output
To build Storybook, use the build-storybook production mode command. The output will be found in the configured outputDir, which defaults to storybook-static.
Web Components Vite framework options - builder
The builder option accepts a Record<string, any> that configures options for the framework's builder. For the Web Components framework with Vite, available options can be found in the Vite builder documentation.
Use decorators to wrap stories with context providers
Use decorators to wrap every story in necessary context providers. This allows you to provide theme providers or other parent components that stories expect.
Default Storybook configuration is permissive
Storybook comes with a default configuration that attempts to customize itself to fit your setup. However, your project may have additional requirements before components can be rendered in isolation, requiring further customization.
Preview file location and naming for other frameworks
The `.storybook/preview.js` or `.storybook/preview.ts` file allows you to customize how components render in Canvas, the preview iframe. This file can be written in JavaScript (preview.js) or TypeScript (preview.ts) for frameworks other than React, Preact, React Native, and Solid.