Skip to content
brix.v2 stable

Search documentation

70 guides

Documentation menu
Docs / Project tooling / StorybookRead Markdown ↗

Own and operate Storybook catalogs

Choose application, standalone library, or workspace catalog ownership and preserve the generated Brix configuration and lifecycle.

Managed Brix Storybook is Preact-only. Managed React applications and separately integrated external React hosts use their own React testing and catalog tooling.

Choose catalog ownership

Application catalog

Initialize at an application root when one product owns the catalog. Brix discovers that application's stories and Panda sources. Storybook receives browser-safe aliases, server guards, styles, and browser test configuration, but it does not enable SSR, route discovery, island output, or the Brix dev server inside Storybook.

Contentful stories use the built-in browser registry from directly relevant adapter sources. Brix strips server loaders and Markdown projections. Stories supply fixture data through ContentfulRenderingProvider. Ordinary stories require no provider. Each content type used by the catalog must map unambiguously to one adapter.

Standalone library catalog

Initialize at a UI-library root when that library owns the catalog. Story tests and the static catalog join the library's brix test, brix build, and brix verify lifecycle. A plain library can opt in when it deliberately contains Preact stories.

Workspace catalog

Initialize once at the workspace root for a shared catalog:

brix create ui-library member-ui
brix create ui-library checkout-ui
brix storybook init

The root .storybook/ is tooling, not a deployable application. It derives story and Panda source globs from matched Brix applications and libraries, including nested and explicit workspace globs while honoring exclusions. External projects are excluded.

Discovery does not establish runtime dependencies or permit cross-application imports. Keep app-owned stories beside app components and reusable stories in a named UI package. Link shared packages to runtime consumers explicitly; avoid an ambiguous shared package. See workspaces.

Understand generated config

Generated files compose these config-time APIs:

  • withBrixStorybook(config, { include }) for aliases, browser guards, and Panda styles
  • defineBrixStorybookTestConfig(plugin, { include }) for Playwright-backed story tests
  • workspaceStoryGlobs(root) and workspaceStorySources(root) for workspace discovery

These are template-owned extension points. Preserve their wrappers rather than reconstructing the integration. Import brix/storybook only from config-time files; application and story code use the browser-safe brix/storybook/test entry point.

Test and build

brix storybook test
brix storybook test src/components/Button.stories.tsx -t "Clicked"
brix storybook build
brix check
brix verify

brix storybook test runs stories in Playwright Chromium. build writes ignored storybook-static/ output. Unqualified brix test includes an integrated catalog, and brix verify includes both tests and the static build. A focused ordinary Vitest run does not also run Storybook.

Brix prepares matching Chromium only when selected, nonempty story tests execute and reuses a working browser cache. For offline repair use brix playwright install chromium. Missing Linux libraries require an administrator to run brix playwright install-deps chromium; custom CI must explicitly set BRIX_BROWSER_INSTALL_DEPS=1 to authorize repair.

Generated reports, screenshots, and traces follow the managed test output policy described in testing. Continue with stores and API routes for component dependencies.