Own and operate Storybook catalogs
Choose application, standalone library, or deliberately combined workspace catalog ownership. Independently themed catalogs keep separate configuration, tests, builds, and deployments.
Managed Brix Storybook is Preact-only. Managed React applications and separately integrated external React hosts use their own React testing and catalog tooling.
Before running init, locate the components, their consuming theme, and any existing .storybook/
directory. The decision in this section determines who owns configuration, test failures,
storybook-static/, and deployment—not merely where a menu appears.
Choose catalog ownership
#Application catalog
#Initialize at an application root when one product or brand owns the catalog. Its .storybook/ directory and generated catalog.ts stay with that application. Brix discovers the owner'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.
An application can include a shared library that it consumes by selecting the workspace package name:
import { defineBrixStorybookCatalog } from "brix/storybook";
export const catalog = defineBrixStorybookCatalog({
root: new URL("../", import.meta.url),
projects: ["foundation"],
});
The library must resolve to that workspace member through the application's dependencies or
devDependencies. A same-named registry dependency with an incompatible version, or an npm alias to
another package, does not authorize selecting local stories. Default/named catalogs and workspace
aliases follow the same resolution as workspace builds; peer/optional dependencies alone do not
authorize selection. Use brix workspace link <owner> <library> for an intentional local link.
The catalog uses the owner's root panda.config.ts. Select designSystem: "foundation" there to
consume its published styles with local token overrides. projects selects stories, not Panda
inheritance or extraction globs. Build dependencies first; package imports resolve published entries,
not Brix source aliases. Colocated library stories that import ./Button.tsx still import source:
selecting them does not turn them into package-consumption tests.
Contentful stories use the built-in browser registry from directly relevant adapter sources. Brix
strips server loader handlers and Markdown projections, retaining response schemas. Stories supply
fixture data through ContentfulRenderingProvider; adapter loaders validate success fixtures
as response-schema input and give components parsed output. Invalid fixtures become failed loaded
results. Storybook does not run application loaders or require the application's server.
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 it owns the catalog. Story tests and the static catalog join brix test, brix build, and brix verify. The root panda.config.ts supplies authoring tokens. For an alternate complete config set pandaConfig: ".storybook/panda.config.ts"; that path must exist. Shared libraries do not implicitly inherit a consumer brand.
Workspace catalog
#Initialize at the workspace root only when a combined catalog is intentional:
brix create ui-library member-ui
brix create ui-library checkout-ui
brix storybook init
The generated root catalog starts with projects: []; a workspace catalog must always make selection explicit. List package names and choose the theme explicitly when combining brands:
export const catalog = defineBrixStorybookCatalog({
root: new URL("../", import.meta.url),
projects: ["store", "foundation"],
pandaConfig: ".storybook/panda.config.ts",
});
External and React applications cannot be selected. Selecting multiple applications with Panda configs without pandaConfig is rejected. The combined Panda config explicitly sets designSystem and include globs for the selected sources. Relative globs resolve from the catalog root, not the config's directory; for example include: ["apps/store/src/**/*.{ts,tsx}", "packages/ui/src/**/*.stories.tsx"] at a workspace-root catalog.
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.
Selected applications' *.store.ts declarations receive automatic identities in previews, tests,
and static builds. Identities distinguish members even when their store paths and provider names
match. Explicit keys and custom-factory keys remain your responsibility and must be unique across
the catalog. This does not change ordinary application production identities or permit libraries
to own an application's cross-island stores. Render the provider in each story that needs it.
Separate authoring from package consumption
#Library-owned stories importing local components are authoring previews. In a combined catalog, their source is compiled under the catalog's Panda config. Recipe overrides can therefore change those previews while the published component retains its compiled recipe. Scanning producer source can also generate a duplicate recipe selector that overrides published CSS in the same catalog.
For a package-consumption check, keep an application-owned catalog with projects: [], author
owner-local stories importing the library's public package entry, and set designSystem in the
owner's Panda config. Keep include scoped to owner sources, without producer implementation or
authoring-story globs. Do not import producer source transitively from these stories. This uses the
existing catalog workflow, not another rendering mode. See the
consumer story scaffold.
Build libraries before running the consumer catalog's tests and static build. A workspace package
import exercises its built entry, but cannot prove the publication allowlist is complete. For that
check, install only the producer's publishable files into a disposable consumer, excluding src,
then run the same stories. Keep native metadata, generated utilities and declaration exports.
Understand generated config
#Generated files compose these config-time APIs:
defineBrixStorybookCatalog({ root, projects, pandaConfig })for explicit story and native styling configurationwithBrixStorybook(config, catalog)for aliases, browser guards, and Panda stylesdefineBrixStorybookTestConfig(plugin, catalog)for Playwright-backed story testsworkspaceStoryGlobs(root)andworkspaceStorySources(root)for workspace discovery
The generated catalog object is imported by both main.ts and vitest.config.ts, keeping source, theme, and Panda choices identical in development, builds, and tests. Preserve these 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.
Panda is always on for managed catalogs and story tests, so the wrappers accept no panda
option; passing one (even panda: true) fails with a pointer to panda.config.ts. Use the owner's
panda.config.ts or an explicit pandaConfig for native styling choices, such as
preflight: false for an existing reset. Keep the generated virtual:brix/storybook-styles
preview import.
A catalog that predates catalog.ts can keep its wrappers and workspaceStoryGlobs discovery. To
adopt explicit selection, add catalog.ts using the examples above, import catalog in both
main.ts and vitest.config.ts, set stories: catalog.stories, and pass catalog as the options
argument to both wrappers. Keep existing addons and preview decorators. Catalog CSS enters through
.brix/storybook.panda.css.
Native utilities use styled-system/; app and catalog can share a config, but do not concurrently
generate different configs into the same directory. Use separate catalog owners or explicitly
coordinated output/import maps for incompatible brands. Config edits fully reload previews;
source-style edits use native CSS HMR. Producer recipes retain published declarations even when
the catalog overrides token values.
Rebuild base/brand design-system packages after Panda upgrades before testing or building catalogs.
For compound group stories, include the group name in the config slot recipe's jsx tracking;
PropsProvider supplies variant defaults, not slot styles. Compare inherited and explicit root
variants in both preview tests and the minified catalog build.
Select, deploy, and link catalogs
#From a workspace root, select an owner explicitly with brix storybook#<member> init|dev|test|build. Unqualified dev, test, or build runs the sole member catalog automatically. If several are integrated, Brix prompts in an interactive terminal; non-interactive use reports the available selector commands. When the workspace root itself has an integration, the unqualified command selects that root catalog.
Each owned catalog builds its own storybook-static/. Deploy each directory independently to its own domain so brands retain separate themes, tests, and release lifecycles.
For navigation across those domains, use Storybook's native refs option in main.ts:
const config: StorybookConfig = {
refs: {
store: { title: "Store", url: "https://storybook.store.example" },
},
// Preserve the generated framework and viteFinal fields.
};
A ref links to a remote catalog. It does not add that catalog to local tests or Panda scanning, and it does not apply the local theme to remote stories. Use explicit projects only when one local combined catalog, one theme, and one test run are actually desired.
Configure the remote static host to allow cross-origin index reads from the composing catalog's
origin, for example Access-Control-Allow-Origin: https://storybook.platform.example. Its framing
policy must also allow that origin to embed the preview. Keep authentication and origin allowlists
appropriate to the catalog's audience; Brix does not configure hosting headers. Without access to
the remote index, a ref can appear in the sidebar with no stories even though the remote catalog
works when opened directly. Verify both sidebar discovery and a rendered remote story after deployment.
The managed Storybook version blocks remote iframe embedding and remote channel messages for live
development servers. Compose built static catalogs instead; their cross-origin composition is
supported. Do not enable insecure channel compatibility options to restore a dev-server embed.
Custom highlight integrations must supply an id and use clickable: true with
HIGHLIGHT_MENU_CLICK, rather than arbitrary click event names; highlight events do not include
element outerHTML. Ordinary Brix stories are unaffected.
Repair dependency drift without replacing a catalog
#brix doctor reports the exact version and the manifest or catalog entry to edit. Apply those
edits, run brix install from the reported installation root, then rerun brix doctor.
For a workspace, versions belong in root pnpm-workspace.yaml; preserve existing named catalogs
and member catalog: references. Review other consumers before changing a shared catalog entry.
Keep authored .storybook files unchanged. brix storybook init is an initializer, not a repair
command for an already integrated catalog.
Isolate existing catalogs from application Vite configuration
#New catalogs select an empty .storybook/vite.config.ts through Storybook's native builder option. This prevents application plugins and asset bases such as /_brix/ from entering the catalog. withBrixStorybook still supplies browser guards, aliases, and Panda styles.
This is the only supported isolation setup. Doctor checks the parsed configuration without executing it. Keep the generated inline const config: StorybookConfig = { ... }; immediately followed by export default config;. Keep framework, options, and builder inline; do not use spreads, duplicate or computed properties, or later mutations in these configuration objects. The Vite entry must contain only export default {}; and optional comments, with no imports or re-exports. Ordinary stories, addons, and other Storybook options remain customizable in main.ts.
Top-level shared-option spreads must precede the explicit framework and viteFinal fields so they cannot override managed configuration. viteFinal must directly return the imported withBrixStorybook, passing its config parameter as the first argument. Arrow expressions and equivalent single-return method or block bodies are supported, including async callbacks. Doctor checks that call, not a comment or unused import; these are structural checks, not execution or a security sandbox for arbitrary configuration code.
brix storybook init does not overwrite an existing integration. If brix doctor reports missing isolation, create .storybook/vite.config.ts with export default {};. In .storybook/main.ts, import fileURLToPath from node:url and preserve the existing framework name while adding:
options: {
builder: {
viteConfigPath: fileURLToPath(new URL("./vite.config.ts", import.meta.url)),
},
},
Keep the existing viteFinal call to withBrixStorybook. Setting configFile: false in viteFinal is too late: Storybook has already loaded the application configuration. Run brix doctor, brix storybook test, and brix storybook build after migrating.
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.