Skip to content
brix.v2.15.0+b120c49

Search documentation

Loading search…

    Documentation menu
    Docs / Getting started / Application typesRead Markdown
    On this page

    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:

    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:

    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, workspaces, and CLI commands for deployment-specific setup.