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

    External workspace applications

    Adopt separately hosted applications, integrate React bindings, and configure intentional cross-origin calls to Brix services.

    Use adoption only for an existing application that keeps its own framework and deployment but should participate in the root install and lifecycle. For a new Brix-managed React SPA, create a react-application instead. Start from a clean tree and review the dry run before any write.

    Integrate external applications

    #

    Adopt a separately hosted non-Brix member into root installation ownership:

    brix workspace adopt apps/admin --dry-run
    brix workspace adopt apps/admin
    

    The project retains its framework scripts and declares brix.project: "external". Root brix dev runs each member's dev script. If the project has only a start script, adoption reuses it as dev only when it is a recognized development server, such as react-scripts start, ng serve, gatsby develop, or vite, and the plan lists that addition. A production start (for example next start or node dist/main.js) is left untouched; add a dev script yourself so brix dev does not skip the member. Adoption refuses a member that has its own pnpm-workspace.yaml or package.json#workspaces, because their settings and catalogs cannot be merged safely; move what the application needs into the root pnpm-workspace.yaml, delete the member file, and retry. Adoption snapshots the manifests, lockfiles, managed skills, and installed dependency trees it may mutate. A formatting, install, skill reconciliation, or doctor failure restores that managed state.

    An external project reads workspace libraries' built dist/ output. Brix builds every library it depends on, and everything those libraries depend on, before root or focused commands, and brix dev watches them, including focused brix dev#<member> and plain brix dev inside the member. A Vite-based project can instead compile library source: declare "brix": { "project": "external", "libraries": "source" } and add the brix-source condition to its Vite and TypeScript configuration, as described in Library source and build output.

    Both preview and execution report existing workspace-health blockers before installing. Fix unrelated member diagnostics first. The target's manifest and nested lockfile migration issues remain eligible for adoption; the final workspace still must pass doctor or the transaction rolls back.

    Transactions normalize stable symlinked parents, but reject symlink-managed roots and unsupported nested links before mutation. Ordinary package links inside node_modules and generated skill links remain supported. Do not edit managed paths concurrently. On POSIX, package-engine cancellation signals the process group and escalates to SIGKILL after 500 ms, followed by a bounded 50 ms scheduling grace. This is best effort, not proof that writers have stopped before rollback. Detached processes in other groups are not covered. Windows signals only the direct child: stop any remaining install processes before recovery or retrying.

    For an existing React host that needs Brix hooks:

    brix workspace integrate react apps/admin --dry-run
    brix workspace integrate react apps/admin
    

    Integration requires an adopted external member and refuses an unadopted one with the brix workspace adopt command to run first. It installs the matching @brix/react, aligns React and ReactDOM, and records the React integration. It does not turn an external host into a managed react-application. For a new managed SPA, use brix create react-app; for Contentful, use brix create contentful-app. See React applications.

    Configure cross-origin browser calls

    #

    Sharing a contract does not enable CORS. When a browser application calls a separately deployed BFF, pass the BFF origin as baseUrl:

    const result = await executeApi(basketApiContract, {
      baseUrl: "https://basket-api.example.com",
      params: { basketId: "basket-123" },
    });
    

    The BFF must explicitly allow the browser application's origin twice: Hono's CORS middleware lets the browser read responses, and Brix's cross-site mutation guard must trust the origin before it accepts POST, PUT, PATCH, or DELETE requests, which it otherwise rejects with 403. Configure both in the BFF's server setup:

    src/brix.server.ts
    "use server";
    
    import { cors } from "brix/hono/cors";
    import { defineBrixServer } from "brix/server";
    import { brix } from "./brix.ts";
    import { env } from "./env.server.ts";
    
    const portalOrigin = "https://portal.example.com";
    
    export const brixServer = defineBrixServer(brix, {
      env,
      csrf: { trustedOrigins: [portalOrigin] },
      middleware: [cors({ origin: portalOrigin, credentials: true })],
    });
    

    Keep the existing route-factory exports below this declaration. Use exact origins, never * with credentials, and keep the allowlist in the BFF rather than in a shared contract library. See cross-site mutation protection.

    After integration, run the external member's own checks and a browser request against the deployed BFF origin. A shared contract proves types; it does not prove DNS, TLS, CORS, or credentials.