bubbles-express-generator

Scaffold an Express backend with your preferred stack:

• JavaScript or TypeScript
• MongoDB (Mongoose) or PostgreSQL (Drizzle)
• npm or Bun workflow

Table of contents

• Installation
• Usage examples
• CLI output style
• Architecture and folder structure
• Configuration and env variables
• Testing and quality checks
• Safety behavior
• Optional AGENTS.md and CLAUDE.md
• Documentation index
• Contributing
• License and credits

Installation

No install (recommended)

npx bubbles-express

bunx --bun bubbles-express

Global install (optional)

npm install -g bubbles-express-generator

bun add -g bubbles-express-generator

Usage examples

Interactive flow

npx bubbles-express

Fully non-interactive flow

npx bubbles-express my-api --ts --pg --pm npm

bunx --bun bubbles-express my-api --js --mongo --pm bun --skip-install

Supported template matrix

• js-mongo
• js-pg
• ts-mongo
• ts-pg

CLI output style

The CLI favors concise, line-based output:

• minimal startup context
• plain help sections (Usage, Flags, Examples)
• direct danger messaging for destructive flows
• compact success summary with one signature line

Example success output:

Project created successfully.
Project folder: my-api
Language: ts
Database: pg
Package manager: npm
Small scaffold. Big momentum.
Next steps:
  cd my-api
  npm run dev

Architecture and folder structure

bubbles-express-generator/
├─ cli/                       # generator entrypoint + prompt/copy/install flow
├─ templates/                 # scaffold templates
│  ├─ js-mongo/
│  ├─ js-pg/
│  ├─ ts-mongo/
│  ├─ ts-pg/
│  └─ agent-instructions/
│     ├─ js/                  # optional AGENTS.md / CLAUDE.md for JS projects
│     └─ ts/                  # optional AGENTS.md / CLAUDE.md for TS projects
├─ tests/                     # CLI integration tests
├─ documentation/project-docs/# focused internal project docs
├─ README.md
└─ CHANGELOG.md

Generated projects use a src/ structure for both JS and TS templates.

Configuration and env variables

CLI flags

• --ts or --js: language
• --mongo or --pg: database
• --pm <bun|npm>: package manager
• --skip-install: scaffold only, no dependency install
• -h, --help: show help

Generator env vars

• BUBBLES_PM=bun|npm: package manager override
• BUBBLES_SKIP_INSTALL=1: skip dependency installation

Generated project env vars

• CORS_ORIGIN: comma-separated CORS allowlist (dev defaults to localhost)
• TRUST_PROXY=1: enables app.set('trust proxy', 1)
• NODE_ENV=development: enables pretty-printed HTTP logs via pino-pretty; production uses default logger transport settings.

Non-interactive runs must include --pm or BUBBLES_PM.

Testing and quality checks

Root project commands:

• npm run lint
• npm run test
• npm run dev

GitHub Actions CI (.github/workflows/test.yml) runs on ubuntu-latest with Node.js 22, installs dependencies with npm ci, then runs:

• npm run lint
• npm run test

Bun equivalents:

• bun run lint
• bun run test:bun
• bun run dev:bun

Generated project commands include:

• dev
• lint
• test
• typecheck (TypeScript templates)

TypeScript templates use a Node-focused tsconfig profile tuned for Express APIs:

• module/moduleResolution: nodenext
• target: es2022 with lib: ["ES2022"]
• stricter safety flags like exactOptionalPropertyTypes and noUncheckedIndexedAccess

When Bun is selected in scaffolding, generated test scripts stay Vitest-based (bunx vitest run and bunx vitest) to match the template test suites.

Safety behavior

When scaffolding into . and the directory is non-empty:

1. CLI shows a high-friction danger warning.
2. You can choose:
   • use a new project name
   • overwrite current directory
   • cancel
3. Overwrite requires typing DELETE_CURRENT_DIR.

If confirmation is wrong, scaffolding is canceled without mutating files.

Optional AGENTS.md and CLAUDE.md

During interactive setup, the CLI asks two separate questions:

• Add AGENTS.md?
• Add CLAUDE.md?

If selected, files are copied to the generated project root from:

• templates/agent-instructions/js/ for JavaScript templates
• templates/agent-instructions/ts/ for TypeScript templates

Documentation index

• documentation/project-docs/structure.md
• documentation/project-docs/cli-behavior.md
• documentation/project-docs/output-style.md
• documentation/project-docs/templates.md
• documentation/project-docs/configuration.md
• documentation/project-docs/testing.md
• documentation/project-docs/dependencies.md
• documentation/project-docs/contributing.md

Contributing

• Open an issue for bugs or feature ideas.
• Keep PRs focused and include tests for behavior changes.
• Run npm run lint and npm test before opening a PR.
• Keep JSDoc intent-first: explain purpose, usage, expected inputs, and return behavior; avoid comments that only restate implementation.
• See documentation/project-docs/contributing.md for PR description guidelines.

License and credits

• License: MIT (LICENSE)
• Author: Manuel Fahrenholz (mrbubbles-src)