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 workflows and deployment

    Run complete or focused lifecycle commands, build applications independently, and diagnose workspace ownership and installation.

    Run these commands from a workspace created as described in workspace architecture. You should have one root lockfile and direct workspace:* links before relying on root orchestration.

    Workspace link and adoption commands check existing workspace-health blockers before installation, including in --dry-run. Repair unrelated member errors first; a successful preview is not an install or a guarantee against later failures. Adoption permits the target manifest and nested lockfile issues that it is responsible for migrating, then diagnoses the resulting workspace transactionally. For missing member environment types, root doctor reports a scoped repair such as brix env#apps/backend types; plain brix env types requires an application directory.

    Run root workflows

    #

    From the workspace root:

    brix install
    brix dev
    brix check
    brix test
    brix build
    brix ci
    brix verify
    

    brix dev runs development projects in parallel. Check, test, build, and verify preserve library dependency order and skip an external member's missing phase scripts. brix ci performs the clean, lockfile-exact root installation, reconciles project-pinned skills, and fails if any member application's committed src/env.generated.d.ts is stale; it runs no checks, tests, or builds. brix verify is the complete diagnosis, check, test, and build gate for an installed workspace. Both run only at the workspace root.

    Root brix check, brix format, and brix verify process ordinary root-owned files separately from member trees. Member phase scripts own their files, including custom supported Oxc configs; external members keep their framework's scripts. The root Oxc pass does not override member policy or format an external application's files when its format script is absent.

    Select one project

    #

    Select a unique member by basename, package name, or path:

    brix doctor#checkout-bff
    brix check#commerce-contracts
    brix test#checkout-bff --project node
    brix build#apps/checkout-bff
    brix start#checkout-bff
    

    An existing workspace-relative test path selects its owner automatically:

    brix test apps/checkout-bff/src/features/checkout/route.test.ts -t "returns checkout"
    brix test apps/checkout-bff/e2e/checkout.spec.ts -t "places an order"
    

    A selection spanning multiple members is rejected. Focused node tests do not run the root Storybook catalog or provision browsers. Focused commands build only the selected member's upstream libraries that need build output (see Library source and build output), so starting one member never rebuilds a library that only another member reads. These builds replace dist files in place rather than cleaning first, so running members that read them are not interrupted.

    Focused dev of an application or external project, including plain brix dev inside it, runs the member together with watchers for the libraries it reads as build output, such as a Panda design system or a library an external application imports. Library edits reach the running member without a restart; libraries it compiles from source need no watcher.

    Focused library build and dev first build that library's upstream libraries that need build output, in dependency order, using their build scripts. They do not rebuild the selected library during preparation or build unrelated libraries. The same applies to plain commands inside the member. In library dev, preparation runs once before the selected library's watcher starts; use root brix dev to watch upstream libraries at the same time.

    Workspace lookup stops at a nearer standalone pnpm-workspace.yaml or foreign workspace declaration. An independently installed tool nested in another repository does not inherit an outer Brix workspace's tools or Storybook sources. Keep real workspace members on the shared root install.

    A project is a member only when the nearest Brix workspace's package.json#workspaces patterns select it; init, doctor, create, lifecycle commands, and the launcher share that rule. node_modules directories are never members, and the launcher accepts *, **, ?, and {a,b} patterns, rejecting other glob syntax instead of guessing. Keep pnpm-workspace.yaml#packages identical to package.json#workspaces: brix init rewrites it from the manifest and brix doctor reports drift. A member must not declare its own pnpm-workspace.yaml or nested workspaces; doctor reports either, and move required settings and catalog entries to the root before deleting the member file. Creating a project at a path selected by the workspace patterns makes it a member even when you run brix create from a non-member directory such as apps/.

    Build and deploy independently

    #

    Build all projects from one revision with brix verify, or focus an application in its deployment pipeline:

    brix build#checkout-bff
    PORT=3000 brix start#checkout-bff
    

    Deploy each application's own output and runtime configuration. Applications can deploy the same repository revision on different schedules, but one workspace intentionally shares one Brix version and lockfile. Projects requiring incompatible framework versions belong in separate workspaces.

    Diagnose the workspace

    #
    brix inspect workspace --json
    brix doctor --json
    brix ci
    brix verify
    

    Confirm one root lockfile, direct workspace:* links, no application-to-application dependencies, unique package names and basenames, and separate output for every deployable member. Member node_modules directories may exist as part of the one root-managed isolated installation; members must not own nested lockfiles or standalone installs.

    Continue with Storybook, publishing releases, and CLI commands.