create-bb-app

Scaffold a production-shaped NestJS backend with hexagonal architecture: pure domain, use cases, ports and adapters, a users slice you can copy from, health checks, Docker, migrations and tests already wired.

Documentation: carloscasteher.github.io/backend-boiler-cli

npx @carloscasteher/create-bb-app my-api

The generated project passes its own typecheck, lint, format:check, test and test:e2e before you write a single line.

What you get

• Hexagonal layering — domain/ (no framework imports), application/ use cases, infrastructure/ adapters, wired per feature module.
• A database, your choice — PostgreSQL with TypeORM (migrations and seeds included) or MongoDB with Mongoose.
• In-memory adapters for tests — every repository has an in-memory twin, so unit and e2e tests run with no database and no Docker.
• Domain events (optional) — an EventBus port with a Nest EventEmitter adapter and an in-memory one for tests.
• Health checks — liveness plus per-adapter readiness checks for the database and the event bus.
• The boring parts, done — Docker Compose, .env handling with validated config, ESLint, Prettier, Vitest, husky and commitlint.
• AI tooling (optional) — AGENTS.md, agent skills and editor rules, or a clean project without them.

Usage

Run it with your favourite runner; the wizard asks for anything you do not pass as a flag.

npx @carloscasteher/create-bb-app          # npm
pnpm dlx @carloscasteher/create-bb-app     # pnpm

Scaffold into the current directory with .:

mkdir my-api && cd my-api
npx @carloscasteher/create-bb-app .

Non-interactive, for scripts and CI:

npx @carloscasteher/create-bb-app my-api --database=postgres --events --agents-skills --yes

Flags

| Flag | Description | | ------------------------------ | --------------------------------------------------------------------- | | [project-name] | Target directory and package name, kebab-case. . scaffolds in place | | --database <postgres\|mongo> | Persistence adapter; the two are mutually exclusive | | --events / --no-events | Include or skip the domain events installer | | --agents / --no-agents | Include or skip all AI tooling (skills, Cursor, Serena) | | --agents-skills | Include .agents, AGENTS.md and skills-lock.json | | --agents-cursor | Include .cursor | | --agents-serena | Include .serena | | --skip-install | Do not run pnpm install after scaffolding | | --yes | Accept defaults for everything not passed as a flag | | -v, --version | Print the CLI version |

AI tooling is opt-in: with --yes and no --agents* flags, none of those files are copied. Git is always initialized (git init on main) without an initial commit.

After scaffolding

cd my-api
pnpm docker:up          # start postgres or mongo
pnpm migration:run      # postgres only
pnpm start:dev

Tests need neither of those: pnpm test and pnpm test:e2e run against in-memory adapters.

Requirements

• Node.js 24 or newer, both to run the CLI and for the projects it generates
• pnpm for the generated project — enable it with corepack enable pnpm
• Docker only if you want a real database locally

How it works

The CLI copies template/base and then applies installers: self-contained feature overlays under template/extras/<id>/ that contribute files, dependencies, scripts and environment variables. The root ApiModule and HealthCheckModule are composed from the chosen set and formatted with the generated project's own Prettier config.

src/
├── cli.ts                  # argument parsing and orchestration
├── prompts.ts              # interactive wizard and input validation
├── installers/             # postgres, mongo, events + shared dependency versions
└── helpers/                # copy, merge, compose, format
template/
├── base/                   # Nest skeleton, shared kernel, liveness health check
└── extras/
    ├── postgres/           # TypeORM, users repository, docker, migrations
    ├── mongo/              # Mongoose, users repository, docker
    └── events/             # Domain event primitives, EventBus adapters, demo health check

Adding a feature means adding an installer: drop the files in template/extras/<id>/, declare what it merges into package.json, and the wizard does the rest.

Roadmap

Observability installers following the same pattern: structured logging with Pino, Prometheus metrics with a dockerized Grafana dashboard, and distributed tracing with OpenTelemetry.

Documentation site

Detailed docs (architecture, domain events, errors, AI workflow) live under docs/ and deploy to GitHub Pages on push to main:

pnpm docs:dev               # local preview
pnpm docs:build             # static site → docs/.vitepress/dist

Changelog

Every release is listed in the changelog.

Contributing

pnpm install
pnpm dev                    # run the CLI from source
pnpm check                  # lint, format, types and unit tests
pnpm test:smoke             # scaffold real projects and run their toolchain
pnpm docs:dev               # VitePress docs locally
pnpm changeset              # describe your change for the next release

License

MIT