> [Agent navigation index](/llms.txt)

# 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:

```ts
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:

```sh
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:

```ts
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](/docs/workspaces.md).

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](/docs/storybook-stories.md#test-a-built-package-in-a-consumer).

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 configuration
- `withBrixStorybook(config, catalog)` for aliases, browser guards, and Panda styles
- `defineBrixStorybookTestConfig(plugin, catalog)` for Playwright-backed story tests
- `workspaceStoryGlobs(root)` and `workspaceStorySources(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`](https://storybook.js.org/docs/sharing/storybook-composition) option in `main.ts`:

```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:

```ts
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

```sh
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](/docs/testing.md). Continue with [stores](/docs/stores.md) and [API routes](/docs/api-routes.md) for component dependencies.
