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

# Integrate an external React host

Adopt an independently generated React host into a Brix workspace and add Brix bindings without replacing its build system.

## Integrate an existing external React host

An independently generated or hosted React application can remain external while the workspace owns installation:

```sh
brix workspace adopt apps/admin --dry-run
brix workspace adopt apps/admin
brix workspace integrate react apps/admin --dry-run
brix workspace integrate react apps/admin

```

Adoption moves installation to the workspace root, records `brix.project: "external"`, and retains the host's scripts and framework configuration. React integration works only on an external member; for an unadopted member it stops and names the `brix workspace adopt` command to run first. It pins `brix` and `@brix/react` to the workspace's immutable Brix version, aligns `react` and `react-dom` (plus their type packages as development dependencies) with the versions Brix supports, and records `brix.integrations.react: true`. It does not convert the host into a managed React application or replace its build system; `brix doctor` later checks that the host, Brix hooks, and signals resolve one React runtime.

Use `@brix/react` for hooks and runtime bindings after integration. Keep browser mounting and build setup under the external host's ownership unless its bundler can deliberately consume the adapter's subpaths. Preview first: adoption and integration are transactional, but existing files may make the plan invalid.

## Verify the external integration

From the workspace root, check ownership and run the external host's existing lifecycle scripts.
Select the member by package name, directory name, or path:

```sh
brix inspect workspace --json
brix doctor
brix check#admin
brix test#admin
brix build#admin
brix verify

```

Focused `dev`, `check`, `test`, `build`, and `format` commands run the member's package script of
the same name; a missing script fails rather than being invented. `check` and `build` first run the
workspace boundary checks, and `test` runs with `CI=true`. Root `brix verify` runs each member's
`check`, `test`, and `build` scripts and skips members that do not define one, so confirm that the
host defines the phases you rely on. Other commands, apart from `install`, `run`, `watch`, `exec`,
`dlx`, and `deps`, are unavailable for an external member. React components use the
host's React test toolchain; Brix's `brix/test/browser` renderer and managed Storybook are Preact-only.

If integration fails, inspect the reported rollback result, fix the first incompatible manifest or
dependency setting, and retry the dry run. Do not add a second React installation to work around a
runtime identity mismatch. After success, test one Brix hook in the real host, including a state
update, and exercise any cross-origin API call against its intended backend.

See [environment configuration](/docs/environment.md), [workspaces](/docs/workspaces.md), and [CLI commands](/docs/cli.md) for deployment-specific setup.
