configuration

333 notes in this subject, read out of this brain and free to use. This is page 6 of 6.

Build configuration errors appear during CLI execution

If errors appear on the CLI when running the `yarn storybook` command, you likely need to make changes to Storybook's build configuration. This may involve using presets, configuring Babel, or adjusting Webpack configuration.

Create story files for components

Create a `.stories.js`, `.stories.ts`, or `.stories.svelte` file to accompany a component. This file defines stories for that component.

Runtime errors indicate compilation problems

If Storybook builds successfully but an error appears immediately when connecting to it in the browser, one of the input files is likely not compiling or transpiling correctly for browser interpretation. Check Babel and Webpack settings to ensure component code works correctly. Storybook supports evergreen browsers.

Components may expect specific context environments

If a particular story has a problem rendering, it often means the component expects a specific environment to be available. A common frontend pattern is for components to assume they render in a specific context with parent components higher up the rendering hierarchy, such as theme providers.

New story creation via file copying

To create a story file for a new component, copy and paste an existing story file next to the component source file, then adjust it for your component.

Creating story from Controls panel

If a component already has other stories, you can use the Controls panel to adjust the value of a control and then save those changes as a new story.

Editing story via Controls panel

Using the Controls panel, you can update a control's value for a story, save the changes, and the story file's code will be updated automatically.

Story code editing directly

You can always update a story's code directly by editing the story file and adding named exports for your story.

Svelte CSF feature not available with template syntax

The feature to create new stories via the plus button is not supported with the Svelte template syntax story format. To use this feature with Svelte, you must use Storybook's Component Story Format (CSF).

Hot reloading for stories

When you edit a component's code or its stories, Storybook will instantly re-render in the browser without requiring a manual refresh.

Story definition and purpose

A story captures the rendered state of a UI component. Developers write multiple stories per component that describe all the interesting states a component can support.

Story files naming convention for non-Svelte renderers

Story files for non-Svelte renderers end with .stories.js or .stories.ts

Story files naming convention for Svelte

Story files for Svelte end with .stories.svelte

Component Story Format (CSF) standard

Component Story Format (CSF) is an ES6 modules-based standard for writing component examples in Storybook.

Svelte CSF template syntax

Svelte stories can be written using Svelte native template syntax via a community-led project called Svelte CSF, in addition to the standard Component Story Format (CSF).

Story object structure

A story is an object that describes how to render the component in question, defining the component's state and arguments.

Args in stories benefits

Using args in stories has multiple benefits: the component's callbacks are logged into the Actions panel, and the component's arguments are dynamically editable in the Controls panel, allowing adjustment of controls during development.

Creating new story with plus button in React

In React, you can click the plus button in the Storybook sidebar to search for your component and have a basic story created automatically.

Storybook is compatible with continuous integration workflows

Storybook is compatible with continuous integration workflow. You can add it as a CI step to automate user interface testing, review implementation with teammates, and get signoff from stakeholders.

Storybook is a development-only workshop for isolated component development

Storybook is packaged as a small, development-only workshop that lives alongside your app. It provides an isolated iframe to render components without interference from app business logic and context, allowing you to focus development on each variation of a component, even hard-to-reach edge cases.

Stories capture UI variations as a declarative syntax

Stories are a declarative syntax for supplying props and mock data to simulate component variations. Each component can have multiple stories, with each story demonstrating a specific variation of that component to verify appearance and behavior. Stories are then used in development, testing, and documentation.

Storybook runs in a separate node process during development

During development, Storybook runs in a separate node process. If you are working on UI in isolation, the only thing you need to run is Storybook.

Storybook is powered by Component Story Format (CSF) open standard

Storybook is powered by Component Story Format, an open standard based on JavaScript ES6 modules. This enables stories to interoperate between development, testing, and design tools. Each story is exported as a JavaScript function enabling reuse with other tools without vendor lock-in.

Recommended Component-Driven workflow for Storybook

The recommended workflow is: (1) Build each component in isolation and write stories for its variations. (2) Compose small components together to enable more complex functionality. (3) Assemble pages by combining composite components. (4) Integrate pages into your project by hooking up data and business logic.

Stories can be reused with testing tools like Jest, Vitest, and Testing Library

Stories can be imported into other JavaScript testing tools. You can reuse stories with Jest or Vitest and Testing Library to verify interactions, put them in Chromatic for visual testing, audit story accessibility with Axe, or test user flows with Playwright and Cypress.

Storybook provides built-in workflows for Interaction, Accessibility, and Visual testing

Storybook offers built-in workflows for automated Interaction testing, Accessibility testing, and Visual testing. Stories provide a pragmatic, reproducible way of tracking UI states for testing purposes.

Storybook auto-generates documentation from stories

Storybook auto-generates documentation from stories. Stories index all components and their various states, making it easy for teams to find and reuse existing UI patterns.

Disable package composition refs in main.js

Consumers can configure how composed Storybook packages behave by disabling the ref element in the .storybook/main.js configuration file.

Mocking callback functions with fn and play functions

When passing `fn` functions as `args` for callback functions, add a play function which interacts with the component and assert whether the callback function was actually called.

Play function parameters: canvas and canvasElement

Play functions receive a `canvas` parameter that has testing-library-like query methods built in, and a `canvasElement` which is the actual DOM element. Use `canvas` directly for queries like `canvas.getByLabelText('Submit')`. Alternatively, use `canvasElement` with the `within()` function imported from 'storybook/test': `within(canvasElement).getByLabelText('Submit')`. Do NOT use `within(canvas)` as it is redundant.

Story writing best practices

When writing stories, cover every distinct piece of business logic and state the component can reach including happy paths, error/edge states, loading, permissions/roles, and empty states. For interactive components, add Interaction tests using play functions that drive the UI with utilities like fn and userEvent. Provide realistic props, state, and mocked data with meaningful labels. Assert visible outcomes of interactions using role/label-based queries. Use semantic roles/labels for accessibility. Use clear story names that describe the scenario and group related variants logically without duplication.

Always write Storybook stories for components

Always write a Storybook story for any component written. When editing a component, ensure appropriate changes have been made to the stories for that component.

Story format and imports guidelines

Import Meta and StoryObj from the framework package. Import test helpers from storybook/test (not @storybook/test). Keep stories minimal with only what is needed to demonstrate behavior.

Give your agent this brain