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

# Workspace architecture and libraries

Create a workspace, inherit root tooling policy, and share libraries, contracts, and exact dependencies across explicit project boundaries.

Use this order: create members, decide which code is deployable, link each library to its direct
consumer, export a public API, then run the root checks. Do not begin by moving source through
relative paths; that hides ownership instead of establishing it.

## Create a workspace

```sh
brix create workspace commerce-platform
cd commerce-platform
brix create app browse-bff
brix create app checkout-bff
brix create react-app customer-portal
brix create library commerce-contracts
brix create ui-library member-ui

```

Bare application names go under `apps/`; bare library names go under `packages/`. Pass an explicit path when the workspace uses custom globs. Workspace patterns may use `*`, `**`, `?`, `{a,b}` alternatives, and leading `!` exclusions; a leading `./` or trailing `/` is ignored. Character classes, extglobs, and brace ranges are rejected by discovery, `brix create`, `brix doctor`, and the launcher alike, so a member is never routed differently from inside it and from the root.

The UI-library template contains a component and a library test but no stories, so a fresh member
passes `brix check` without optional Storybook tooling. Run `brix storybook#member-ui init` to
install that tooling; it also adds a colocated starter story for the template `Button`. A root
catalog is an optional, explicit combined selection rather than the default owner and does not add
member stories. See [catalog ownership](/docs/storybook-catalogs.md).

A typical layout is:

```text
commerce-platform/
├── apps/
│   ├── browse-bff/
│   ├── checkout-bff/
│   └── customer-portal/
├── packages/
│   ├── commerce-contracts/
│   └── member-ui/
├── .brix-hooks/
├── .node-version
├── oxfmt.config.mts
├── oxlint.config.mts
├── package.json
├── pnpm-workspace.yaml
└── pnpm-lock.yaml

```

Put projects with runtime configuration and a deployment under `apps/`. Put code imported by other projects under `packages/`. Each application owns its routes, environment, tests, build, and deployment; shared libraries are not deployed as services.

## Inherit root tool policy

Workspace members inherit the root `.node-version`, `oxfmt.config.mts`, `oxlint.config.mts`, managed
skills, and Git hooks. Creation does not copy them into each member. Keep formatting and linting
decisions in the root configs and express member exceptions with root-relative `overrides`, such as
`apps/admin/src/**/*.tsx`. Config globs are relative to the file that declares them.

Open the workspace root in editors so the official Oxc extension finds the shared local binaries and
configs. Add a member config only for a genuine separate boundary: it replaces ancestor discovery
rather than automatically extending the root, so explicitly compose any root settings that should
still apply and retain the Brix config helper. Member-owned TypeScript/build config, environment,
`.brix`, and project-specific guidance remain in the member.

Hooks live only at the Git root under `.brix-hooks/`. Member `brix init` and workspace upgrades remove
unchanged generated member Oxc configs, matching Node pins, and default hook directories so members
inherit root policy; customized files are left untouched. See
[linting and formatting](/docs/linting-formatting.md#configure-a-workspace-at-the-root) for examples.

## Establish import boundaries

Applications must not depend on or import other deployable applications. Move intentionally shared contracts, components, business logic, or test utilities into a clearly named library.

Link every library directly to each consumer:

```sh
brix workspace link apps/checkout-bff packages/commerce-contracts --dry-run
brix workspace link apps/checkout-bff packages/commerce-contracts
brix create library test-support
brix workspace link apps/checkout-bff packages/test-support --dev

```

Use `--dev` only when the dependency is needed exclusively for build or test work. Import through the package's public API:

```ts
import { basketApiContract } from "commerce-contracts";

```

The specifier is the library's `package.json` name, not its directory path. The creation command
above names it `commerce-contracts`; a scoped name such as `@commerce/contracts` works only if that
is the actual declared package name. Export the contract from the library's `src/index.ts`;
Brix applications compile it from source, so there is no build step before consuming it (see
[Library source and build output](#library-source-and-build-output)). The example below defines
that public contract.

Do not use parent-relative paths, `file:` tricks, or symlinks into another member's `src/`. Brix resolves static imports, exports, known dynamic imports, and `require()` calls to canonical paths. `brix workspace link` rejects application dependencies, and `brix doctor` catches equivalent hand-written edges. Library cycles are rejected.

Linking preflights existing workspace health before changing dependencies, including with
`--dry-run`. Repair reported blockers before retrying; a proposed valid edge does not make an
already unhealthy workspace valid.

The library graph follows resolved local dependencies, not names alone. A registry dependency on
`other@1` does not create an edge to a local `other@9`. Brix resolves default and named catalogs
before classifying edges, and recognizes explicit workspace aliases and local directory links.
Use `workspace:*` for deliberate local dependencies rather than relying on registry range matching.

Keep application-owned island wrappers and stores inside the application so its build can assign stable identities. A shared UI library can export ordinary Preact components; the consuming application declares the island boundary with a wrapper component that renders the library component, as described in [Make a library component an island](/docs/islands.md#make-a-library-component-an-island). Re-exporting or aliasing the imported component is rejected, because Brix would mark the library's shared component everywhere it renders. Doctor reports `"use island"` modules and `createStore` tuples in a library.

### Library source and build output

Library templates export their TypeScript source through the `brix-source` condition ahead of
the built files:

```json
"exports": {
  ".": {
    "brix-source": "./src/index.ts",
    "types": "./dist/index.d.mts",
    "import": "./dist/index.mjs"
  }
}

```

Brix applications resolve `brix-source` in development, tests, type checking, and production
builds, so they compile library source together with their own. A library edit reaches a running
application the way an application edit does, with no library rebuild: changes reached only
through islands hot-update and keep their state, and changes to modules a server-rendered page
imports reload the page. Type errors in library source are reported where an application uses it.

Brix builds a library only when something reads its `dist/` output:

- an external workspace project that depends on it, such as a Next.js application;
- another library that depends on it, because a library's own tests run against the build output
  of the libraries it imports;
- a Panda design system, whose `dist/panda` artifacts consumers replay;
- a library whose exports do not all declare `brix-source`.

Everything such a library depends on is built with it. Commands build these libraries in
dependency order before running, and `brix dev` watches them; other libraries are never built
during development. Libraries without the condition keep working as before, because they are
built. Add `brix-source`, pointing at each export's source entry, to let applications compile one
directly.

An external project whose bundler resolves custom export conditions, such as a Vite-based
application, can opt into source with `"brix": { "project": "external", "libraries": "source" }`.
It must also resolve the condition itself: add `brix-source` to its Vite `resolve.conditions` for
both client and server environments, and to `compilerOptions.customConditions`. Brix then stops
building libraries for it. Next.js does not support custom export conditions, so keep Next.js
applications on build output.

### Build styled UI libraries

A styled UI library authors root `panda.config.ts`, maps `#brix/panda/*` to
`./styled-system/*/index.js`, and builds with `defineBrixLibraryBuildConfig`. Native Panda emits
`dist/panda/{lib.json,preset.mjs,buildinfo.json}` and package exports. Publish `dist` plus
`styled-system`, preserving those exports. Declare producer tokens so compiled recipes reference
CSS variables, then override their values in consumers.

Consumers select a design system explicitly with `designSystem: "foundation"`; linking a dependency
does not select it. A brand library can extend the base and publish its own native manifest, and an
app selects that brand. Keep runtime dependency edges resolvable and build base → brand → app.
After a Brix upgrade that changes Panda, rebuild the whole chain before app or catalog
verification: Panda releases can change CSS ordering and build-info encoding. Native `base-ui/types` and `brand-ui/types` exports are
type-only: use `import type`, including when emitting declarations from an extended brand package.
No source aliases or consumer runtime rebinding are involved. Statically extracted producer recipe
CSS and its recorded variants stay compiled, so a same-named consumer recipe does not rewrite them.
Inherited recipe `staticCss` is different: Panda evaluates it against the consumer's merged config
recipe, so overrides affect those declarations and can cover runtime-selected variants. Producer
recipe functions still return their published class names; keep class and variant keys compatible.
Prefer tokens for value-only branding and brand-specific components for incompatible changes.

Keep authoring and consumption checks separate. The generated library story imports local source;
an application-owned consumption story imports the built public package. Keep that application's
catalog at `projects: []` and Panda includes scoped to its own sources so producer implementation
is not recompiled under the consumer config. Repeat against only publishable files in a disposable
consumer to verify packaging, not just workspace resolution. See the
[consumer story scaffold](/docs/storybook-stories.md#test-a-built-package-in-a-consumer).

Run library watch builds during development and test the actual published outputs. Missing/error
metadata and stale fallback fail preparation. See [design-system composition](/docs/styling-components.md#extend-base-brand-app)
and [required white-label tokens](/docs/styling-components.md#require-complete-white-label-tokens).

## Share contracts, not implementations

A browser-safe contract package describes the intentional relationship between independently deployed consumers:

```ts
import { createApiContract } from "brix/contracts";
import { z } from "brix/zod";

export const basketApiContract = createApiContract({
  method: "GET",
  path: "/api/baskets/:basketId",
  response: z.object({ id: z.string(), itemCount: z.number().int().nonnegative() }),
});

```

The owning BFF implements that contract. Other applications consume the contract package, never the BFF's route implementation. See [API routes](/docs/api-routes.md).

## Manage shared dependencies

Add registry dependencies to the consuming member with a focused Brix command:

```sh
brix deps#checkout-bff add date-fns
brix deps#member-ui add lucide-preact
brix deps#checkout-bff why date-fns

```

Brix stores exact third-party versions in the default catalog in `pnpm-workspace.yaml` and writes `catalog:` in member manifests. `brix deps#checkout-bff update date-fns` updates the shared catalog entry, so all consumers on that entry move together. A plain `brix deps update` at the workspace root covers the root and every member. At the root, `add` and `remove` target the root manifest unless you pass `--filter`, `--recursive`, or select a member with `deps#<member>`. Use a named catalog only when the workspace deliberately supports incompatible dependency lines. `catalog:default` and a `catalogs.default` section are treated as the default catalog; declare it in only one of `catalog` or `catalogs.default`.

Run dependency commands from a project or any directory inside it: Brix targets the nearest
`package.json`, as the package engine does, and rebases relative path specifiers such as
`../shared` or `file:../shared` so the manifest records a path relative to that project. Inside a
workspace member this holds too: the launcher selects the member and reports your directory. With an
explicit `deps#<member>` selector run outside that member, write relative paths from the selected
member's directory.

Local libraries use direct `workspace:*` edges rather than catalog entries. Every imported library must be direct; do not rely on root hoisting. The root and every Brix member retain an explicit catalog-backed Brix dependency, while unrelated dependencies in external applications remain owned by their generator.

Bulk and wildcard updates cannot bypass framework ownership in managed Brix projects. External
applications continue to own direct React, Vite, and other host dependencies; use the Brix upgrade
workflow for `brix` and an integrated `@brix/react` adapter.

Expected result: `brix inspect workspace --json` shows an acyclic library graph, and the consumer
imports the package name rather than another member's source path. Continue with
[workspace workflows](/docs/workspaces-workflows.md).
