Bricks

bricks is a CLI for moving source code from one Nx monorepo into another Nx monorepo while keeping a link back to the source commits.

It turns any Git-backed Nx repo into an installable source. Bricks pulls the whole source repo into the consumer workspace's .bricks area, analyzes its Nx projects and package dependencies, then lets the consumer copy apps, libraries, and dependent libraries into their own monorepo as normal committed source files.

Only add sources you trust. Pulling a source installs that repo's dependencies inside its local cache and evaluates its Nx project graph, which can execute source-controlled lifecycle scripts and Nx plugins.

Bricks is for human developers, AI agents, and platform teams that want the speed of copying proven Nx projects without giving up local customization or the ability to keep updating installed bricks from their source commits.

What Bricks Does

• Registers any Git-backed Nx repo as a source.
• Pulls the whole source repo into .bricks/sources/<name> and analyzes it.
• Detects Nx apps and libraries from the project graph, then reads package dependencies and dev dependencies from each project's local package.json.
• Initializes missing Nx tooling referenced by resolved target executors and syncGenerators through nx add.
• Installs source bricks, meaning source code copied from source Nx projects.
• Copies source into the consumer workspace as ordinary code owned by the consumer repo.
• Merges TypeScript aliases for copied projects and copies tracked workspace helpers imported by copied root-level project configs.
• Records the source repo, ref, commit, project path, target path, dependency choices, and install alias in .bricks/config.json.
• Updates installed bricks by comparing the recorded base commit, the local copy, and the new source commit.
• Leaves conflicts in standard Git conflict form so the consumer can resolve them in their normal workflow.

Source, Not Compiled Output

Bricks installs source code, not compiled code. The copied files become normal workspace files that the consumer can edit, commit, build, test, and release. Package dependencies are added only so the copied source can run inside the consumer workspace.

Core Workflow

1. A consumer initializes Bricks in their own Nx workspace.
2. The consumer adds an existing Git-backed Nx repo as a source.
3. Bricks pulls the whole source repo and analyzes its Nx project graph.
4. The consumer installs an app, a library, or a project plus its dependent libraries into target paths in their workspace.
5. The consumer edits, commits, builds, and tests the copied source normally.
6. Later, the consumer updates installed bricks and resolves any normal Git merge conflicts in the local copy.

Quick Start Shape

bricks init
bricks source add talent-platform git@github.com:recruitment-co/talent-platform.git --pull
bricks source projects talent-platform
bricks install talent-platform/job-board-app --with-dependent-libs
bricks merge job-board-app

That flow starts from an existing Nx monorepo. Bricks pulls it, detects apps, libraries, package dependencies, dev dependencies, Nx tooling requirements, and dependent Nx libraries, then copies selected source into the consumer workspace.

In interactive human mode, bricks install can also be run without a reference. It prompts for a configured source, asks before pulling missing source analysis, then lists uninstalled projects from that source.

Each source project owns its package contract through <projectRoot>/package.json. Projects without a local manifest intentionally contribute no package requirements. Root workspace manifests, Nx external graph nodes, and executor inference are not ordinary package dependency sources. Resolved executors and syncGenerators contribute a separate Nx tooling lane initialized through nx add.

Status

Bricks has an executable CLI implementation for the core source lifecycle: initialize a consumer workspace, add and pull Git-backed Nx sources, inspect projects, install source apps and libraries, report status/diffs, merge source updates, and run doctor checks.

The product remains intentionally focused on source-level Nx reuse. Bricks is not a package manager, an Nx replacement, or a hidden runtime framework.

Docs

• Product model defines the product boundary, ownership model, source identity, and install/update lifecycle.
• Command reference defines the source-oriented CLI surface.
• Technology stack defines the implementation contracts for the CLI, core packages, Nx integration, Git, package-manager coordination, and tests.
• Glossary defines the product terms used across the docs.

Development

Install dependencies:

pnpm install

Run the full verification suite:

NX_DAEMON=false pnpm nx run-many -t lint typecheck build test

Verify the packaged CLI artifact:

NX_DAEMON=false pnpm nx run @bricks/cli:package-smoke --skipNxCache

Run consumer-style smoke builds against the current ../bricks worktree:

NX_DAEMON=false pnpm nx run @bricks/cli:local-bricks-smoke --skipNxCache

Run the opt-in remote acceptance test:

BRICKS_REMOTE_E2E=1 NX_DAEMON=false pnpm nx test @bricks/testing --skipNxCache

Run tests only:

pnpm test

Check TypeScript project references:

NX_DAEMON=false pnpm nx sync:check

Format the docs and config files touched by the current spec work:

pnpm exec prettier --write README.md docs/*.md package.json nx.json apps/cli/project.json apps/cli/package.json

Build the CLI binary:

NX_DAEMON=false pnpm nx build @bricks/cli
node apps/cli/dist/bricks.js --help

Release

@otwld/bricks is the only npm package managed by Nx Release. Releases use conventional commits, update the CLI package manifest, generate the workspace changelog, create a Git tag, and publish through the @bricks/cli nx-release-publish target.

Preview a local release without publishing:

pnpm run release:dry-run

Run a local release:

pnpm run release:local

Publish an already-versioned package:

pnpm run release:publish

The manual GitHub Actions Release workflow runs the same Nx release flow from CI. Configure the repository secret NPM_ACCESS_TOKEN with an npm automation token before publishing. The workflow sets npm provenance metadata and exposes a dry-run input for safe release previews. After clearing the previous npm package history, enable the workflow's first-release input for the next publish so Nx does not require an existing release tag.