Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Testing and tooling / Workspaces and librariesRead Markdown
    On this page

    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

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

    A typical layout is:

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

    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:

    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). 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. 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:

    "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.

    Run library watch builds during development and test the actual published outputs. Missing/error metadata and stale fallback fail preparation. See design-system composition and required white-label tokens.

    Share contracts, not implementations

    #

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

    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.

    Manage shared dependencies

    #

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

    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.