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

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

```sh
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](/docs/workspaces-libraries.md#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:

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

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

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

```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](/docs/server-auth-security.md#protect-mutations-from-other-sites).

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.
