Start here
Core concepts
Bricks, the Vault, manifests, versions and adapters: the five ideas the rest of the docs build on.
Brick
A brick (called a module in CLI output) is one folder of source code that does one job and carries a manifest. Examples: auth, waitlist, discount-rules, notification-inbox. Bricks are written in strict TypeScript and target one framework, currently Next.js or NestJS.
When a brick is installed, its files are copied into your project, where you can read and change them. There is no hidden node_modules copy and no runtime dependency on BricoWerx.
A brick can come from three places:
| Source | How | Tool |
|---|---|---|
| An existing project | Lift a module you already wrote | brico capture |
| A specification | Answer an interview; an engine generates and tests the code | Builder |
| A running web app | Observe a feature in the browser; a worker builds it | Scanner |
Vault
The Vault is where bricks live: a directory under git, at ~/.brico/vault by default. Each version of each brick is an immutable snapshot, and an index.json summarises all of them for search. Because it is plain git, you can read it, diff it, review it and revert it. Sharing it means pushing it to a repository. See The Vault.
Manifest
Every snapshot carries a brico.manifest.json, the contract between a brick and the engine. It records the brick’s name, version, framework, files, npm dependencies, required environment variables, exports, compatibility and install path. The engine reads behaviour from the manifest instead of hardcoding it. That is what makes third-party bricks possible.
{
"schemaVersion": 1,
"name": "auth",
"version": "0.1.0",
"description": "JWT authentication with Passport and bcrypt",
"framework": "nest",
"language": "typescript",
"visibility": "private",
"tags": ["security", "jwt", "auth"],
"dependencies": { "@nestjs/jwt": "^10.2.0", "bcrypt": "^5.1.1" },
"env": [{ "name": "JWT_SECRET", "required": true }],
"files": ["auth.module.ts", "auth.service.ts", "jwt.strategy.ts"],
"installPath": "src/auth"
}The full field list is in Manifest and project files.
Versions
Bricks use semantic versioning. A published version never changes. To change a brick, capture it again with a higher --module-version. When you add or upgrade a brick, you can pin it or give a range:
| You write | You get |
|---|---|
auth | The latest version in the Vault |
auth@0.2.0 | Exactly 0.2.0 |
auth@^1.2.0 | The newest ≥ 1.2.0 and < 2.0.0 (for 0.x: < the next minor) |
auth@~1.2.0 | The newest ≥ 1.2.0 and < 1.3.0 |
Project file
A project that uses bricks has a brico.json at its root. It records the detected framework and every installed brick with its version and path. add, upgrade, remove and doctor all read it. Commit it with your code.
Adapters
The engine itself knows nothing about any framework. Framework knowledge sits behind an adapter, which decides where a brick installs by default, which folders look reusable, and which wiring steps to print after add and remove.
| Adapter | Detected from | Default install path |
|---|---|---|
| NestJS | @nestjs/core | src/<name> |
| Next.js | next | src/features/<name> |
Supporting a new framework means adding one adapter package. The engine core doesn’t change. Express, Fastify, Django and Spring are on the roadmap.
Portability and the host
Copying a folder into a different app only works if the folder doesn’t reach out to the app it came from: its import aliases, design system, auth or database. The governing rule is:
The brick rules spell this out as twelve checkable rules. Bricks made by the Builder follow them automatically.