Portable Stories API documentation location
Portable Stories is documented at https://raw.githubusercontent.com/storybookjs/storybook/HEAD/docs/api/portable-stories/index.mdx. It is listed as order 6 in the sidebar navigation.
Storybook · API · all subjects
portable stories
43 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Composed story run method
The run method is a property of the composed story with type (context) => Promise<void> | undefined. It mounts the component and executes all story lifecycle hooks, including the play function. The run method executes loaders, beforeEach hooks, and play function code.
Portable stories default args behavior
By default, the composed story will render the component with the args that are defined in the story. You can also pass any props to the component in your test and those props will override the values passed in the story's args.
Portable stories - Next.js special configuration
When using portable stories in Jest with Next.js projects, you must: configure the next/jest.js transformer to handle Next.js configuration, import composeStories or composeStory from the @storybook/nextjs package (not @storybook/react), and set up internal module aliases to ensure framework configuration works correctly and to mock and assert on them.
CSF Factories as alternative to portable stories in React
If you are using the experimental CSF Factories format, you don't need to use the portable stories API in React. Instead, you can import and use your stories directly.
Portable stories minimum Storybook version
The portable stories API specified in this documentation is available in Storybook 8.2.7 and up. If using an older version, upgrade with npx storybook@latest upgrade. Older versions use the .play() method instead of .run() but are otherwise identical.
Portable stories Jest support - React and Vue only
Portable stories in Jest are currently only supported in React and Vue projects. They are not available for other renderers.
setProjectAnnotations function type signature
The setProjectAnnotations function has the following type signature: (projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => ProjectAnnotation;
setProjectAnnotations usage and timing
setProjectAnnotations should be called once before tests run, typically in a Jest setup file. This ensures that whenever composeStories or composeStory are called, the project annotations are taken into account.
setProjectAnnotations - projectAnnotations parameter
The projectAnnotations parameter is required. Type: ProjectAnnotation | ProjectAnnotation[]. It is a set of project annotations (those defined in .storybook/preview.*) or an array of sets of project annotations, which will be applied to all composed stories.
Composed story play method
The play method is a property of the composed story with type (context) => Promise<void> | undefined. It executes the play function of a given story.
React 18+ requirement for portable stories with Playwright CT
Your project must be using React 18+ to use the portable stories API with Playwright CT. The portable stories API is not yet supported in Next.js with Playwright CT.
Vue module aliasing for template-based components in Playwright CT
If your stories use template-based Vue components, you may need to alias the `vue` module to resolve correctly in the Playwright CT environment. This can be done via the `ctViteConfig` property in the Playwright configuration. Example configuration: set the resolve alias to map 'vue' to 'vue/dist/vue.esm-bundler.js'.
Stories must be composed in a separate file for Playwright CT
Stories must be composed in a separate file than your Playwright test file because Playwright transforms and orchestrates code where part executes in Node and other parts execute in the browser. The separate file should use `composeStories` from '@storybook/your-framework' and export the composed stories, which can then be imported in the Playwright test file.
setProjectAnnotations function signature and parameters
The setProjectAnnotations function has the signature: (projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => ProjectAnnotation. The projectAnnotations parameter is required and accepts either a single set of project annotations or an array of sets of project annotations, which will be applied to all composed stories.
setProjectAnnotations should be called in playwright/index.ts
The setProjectAnnotations API should be called once before tests run in `playwright/index.ts`. This ensures that when `mount` is called, the project annotations are taken into account.
Story pipeline stages
The story pipeline includes three main stages: 1) Apply project-level annotations (from `.storybook/preview.*` file and addons), 2) Compose story (create renderable elements based on passed stories), 3) Render story (load, mount, and execute the play function).
Project annotations not automatically applied in portable stories
In portable stories, project-level annotations from `.storybook/preview.*` and addons are not applied automatically. You must apply them yourself using the setProjectAnnotations API.
mount function handles story pipeline steps in portable stories
The mount function in portable stories within Playwright CT handles preparing the story, loading data, rendering the story, and playing interactions for you.
Play function assertions in portable stories
If your play function contains assertions (e.g. `expect` calls), your test will fail when those assertions fail in portable stories.
createTest function signature
The createTest function has the signature: createTest(baseTest: PlaywrightFixture) => PlaywrightFixture. The baseTest parameter is required and should be the base test function to use, e.g. `test` from Playwright. It returns a Storybook-specific test function with a custom `mount` mechanism.
Portable stories API support in Playwright CT
The portable stories API for Playwright CT is experimental. Playwright CT itself is also experimental. Breaking changes might occur in either library in upcoming releases. Portable stories are currently only supported in React and Vue projects.
Svelte portable stories props override
In Svelte portable stories, the composed story renders the component with args defined in the story by default. To override props for an individual story, use the composeStory function.
Portable stories Vitest support
Portable stories in Vitest are currently only supported in React, Vue, and Svelte projects.
Portable stories Svelte CSF limitation
Portable stories in Svelte are experimental and not supported with the Svelte CSF. To use this feature with Svelte, you must use Storybook's Component Story Format instead.
Vitest addon recommended over direct portable stories API
Storybook recommends testing stories in Vitest with the Vitest addon, which automatically transforms stories into real Vitest tests using the portable stories API under the hood. The direct portable stories API is still available but the addon provides a more streamlined testing experience.
composeStories function signature
The composeStories function has the signature: (csfExports: CSF file exports, projectAnnotations?: ProjectAnnotations) => Record<string, ComposedStoryFn>. It processes component stories, composes each with necessary annotations, and returns an object containing the composed stories.
composeStories csfExports parameter
The csfExports parameter of composeStories is required and takes CSF file exports. You must pass the full set of exports from the CSF file, not the default export. For example: import * as stories from './Button.stories'.
composeStories return value properties
The composed story object returned by composeStories has the following properties: args (Record<string, any>), argTypes (ArgType), id (string), parameters (Record<string, any>), play ((context) => Promise<void> | undefined), run ((context) => Promise<void> | undefined), storyName (string), and tags (string[]).
composeStory function signature
The composeStory function has the signature: (story: Story export, componentAnnotations: Meta, projectAnnotations?: ProjectAnnotations, exportsName?: string) => ComposedStoryFn. It composes a single story for a component.
composeStory story parameter
The story parameter of composeStory is required and specifies which story you want to compose. It accepts a Story export.
composeStory componentAnnotations parameter
The componentAnnotations parameter of composeStory is required and accepts the Meta type. It is the default export from the stories file containing the story being composed.
composeStory projectAnnotations parameter
The projectAnnotations parameter of composeStory is optional and accepts type ProjectAnnotation | ProjectAnnotation[]. It specifies project annotations to be applied to the composed story. This parameter can override project annotations from setProjectAnnotations.
composeStory exportsName parameter
The exportsName parameter of composeStory is optional and accepts a string. Because composeStory accepts a single story, it does not have access to the story's export name. If you must ensure unique story names in tests and cannot use composeStories, you can pass the story's export name here.
setProjectAnnotations function signature
The setProjectAnnotations function has the signature: (projectAnnotations: ProjectAnnotation | ProjectAnnotation[]) => ProjectAnnotation. It should be called once before tests run, typically in a Vitest setup file.
setProjectAnnotations must include preview and addon annotations
The setProjectAnnotations setup file must include preview annotations defined in .storybook/preview.tsx and optional addon annotations exported by addons. It should also include beforeAll code that runs before all tests.
Addon decorators and loaders in portable stories
If a story requires an addon's decorator or loader to render properly, the addon's preview export must be included in the project annotations set. If an addon does not automatically apply the decorator or loader but instead exports them for manual application in .storybook/preview.* (like withThemeFromJSXProvider from @storybook/addon-themes), no additional action is needed as they are already included in previewAnnotations.
Annotations definition
Annotations are metadata applied to a story, including args, decorators, loaders, and play functions. They can be defined for a specific story, all stories for a component, or all stories in the project.
Story pipeline steps
The story pipeline consists of three main steps: (1) Apply project-level annotations from .storybook/preview.* and addons using setProjectAnnotations; (2) Compose the story using composeStories or composeStory to create a renderable component; (3) Run the composed story by calling its run method to mount the component and execute lifecycle hooks including the play function.
Portable stories run method execution
The run method of a composed story executes loaders, beforeEach hooks, and the play function. It mounts the component and executes all story lifecycle hooks. If the play function contains assertions like expect calls, the test will fail when those assertions fail.
Override globals in portable stories
If stories behave differently based on globals (like rendering text in different languages), you can define those global values in portable stories by overriding project annotations when composing a story using the projectAnnotations parameter.
Next.js portable stories in Vitest
To test Next.js stories with Vitest, install and set up the @storybook/nextjs-vite package, which re-exports the vite-plugin-storybook-nextjs package.
React portable stories props override
In React portable stories, the composed story renders the component with args defined in the story by default. You can also pass any props to the component in your test and those props will override the values passed in the story's args.