BricoWerxDocs
Docs menu

Start here

Getting started

Install the brico CLI, capture your first brick and add it to another project in about five minutes.

This guide installs brico, captures a module from one project into a Vault, and adds it to a second project. You need a terminal and git. Supported projects are Next.js and NestJS, written in TypeScript.

Install the CLI

brico is a single static binary with no runtime dependencies. Choose one method:

Install script (macOS, Linux)

bash
curl -fsSL https://raw.githubusercontent.com/ScienceWerx-Inc/bricowerx/main/scripts/install.sh | sh

The script downloads the release binary for your OS and architecture, checks it against the release’s SHA256SUMS.txt, and installs it to ~/.local/bin. To change that, set these variables before running it:

bash
# install a specific version into /usr/local/bin
curl -fsSL https://raw.githubusercontent.com/ScienceWerx-Inc/bricowerx/main/scripts/install.sh \
  | BRICO_VERSION=0.1.0 BRICO_INSTALL_DIR=/usr/local/bin sh

npm

bash
npm install -g brico

The npm package downloads the same checksummed release binary.

From source

Requires Go. The result is the same binary.

bash
git clone https://github.com/ScienceWerx-Inc/bricowerx.git
cd bricowerx/engine
go build -o ../brico ./cmd/brico

Confirm it works:

bash
brico --version
brico doctor

Capture and reuse your first brick

The repository ships two example NestJS apps: examples/nest-source, which has a JWT auth module, and examples/nest-target, which doesn’t. The steps below use a throwaway Vault, so nothing touches your real one. Run them from the repository root.

  1. Point brico at a scratch Vault
    bash
    export BRICO_VAULT="$(mktemp -d)"

    Without this, the Vault defaults to ~/.brico/vault. You can also pass --vault <path> to any command.

  2. Find reusable modules
    bash
    brico --cwd examples/nest-source extract

    extract lists modules that look self-contained, ranked by confidence. --cwd runs a command as if you were inside that directory.

  3. Capture one into the Vault
    bash
    brico --cwd examples/nest-source capture auth -y \
  -d "JWT authentication with Passport and bcrypt" \
  -t security,jwt,auth

    capture scans the module’s files, imports and environment variables, writes a brico.manifest.json, and commits the snapshot to the Vault as version 0.1.0.

  4. Find it again
    bash
    brico list
brico search jwt
  5. Add it to another project
    bash
    brico --cwd examples/nest-target add auth -y

    add copies the files to the framework’s install path, records the module in brico.json, appends its required variables to .env.example, and prints the wiring steps for your framework.

  6. Check the result
    bash
    brico --cwd examples/nest-target doctor

In your own project

bash
cd ~/code/api-one
brico extract                       # what looks reusable here?
brico capture billing -p src/billing -d "Stripe billing" -t payments
cd ~/code/api-two                   # another app on the same framework
brico add billing@^0.1.0

Version ranges follow semver: billing takes the latest version, billing@0.2.0 an exact version, billing@^0.1.0 the newest compatible one and billing@~0.1.0 the newest patch.

A brick records the framework it was captured from, and add refuses to put a NestJS brick into a Next.js app or the other way round. To make one brick usable in any Next.js app regardless of its aliases or design system, follow the brick rules.

Next steps