Adding a Service

You don't have to decide your whole architecture up front. stackr add service adds a new, fully isolated microservice to an existing monorepo and wires it into Docker Compose, the root .env, stackr.config.json, and — if present — the CI matrix.

npx stackr add service wallet

Flags

FlagEffect
--auth-middleware <type>standard | role-gated | flexible | none (default: standard when auth exists)
--webAlso scaffold a per-service Next.js frontend
--mobileAlso scaffold an Expo mobile app
--event-queue / --no-event-queueEnable / disable a BullMQ + Redis worker
--port <n>Explicit REST API port (otherwise auto-allocated above 8080)
--no-installSkip the package-manager install step
--no-testsSkip Vitest scaffolding for this service
--forceBypass the pending-migration refusal
--verboseDetailed output
# A role-gated service with a web frontend on an explicit port
npx stackr add service billing --auth-middleware role-gated --web --port 8083

# A mobile-enabled service with an event queue
npx stackr add service notifications --mobile --event-queue

It's atomic

Adding a service touches managed files you may have hand-edited (docker-compose.yml, the ORM schema, backend/package.json). stackr does this safely:

  1. Validate the request against stackr.config.json (read-only).
  2. Stage every write into a tempdir and dry-run the merged YAML and schema.
  3. Merge new blocks with an additive AST merge — your existing services, comments, and formatting are preserved.
  4. Commit atomically. If any step fails, the project is left byte-identical.

The same generator that runs at init regenerates the harness artifacts, so the new service's AGENTS.md, rules, and skills appear automatically.

Pending migrations

If adding a service changes the auth schema (for example, a new has<Service>Account flag), stackr records a pending migration and refuses further stackr subcommands until you run it and acknowledge:

# run the printed migration, then:
npx stackr migrations ack auth

This guarantees the database and the config never silently diverge. Use --force only if you know the schema is already migrated.

After it runs

  1. npm run setup (or your package manager) to install the new workspace's deps if you passed --no-install.
  2. npm run docker:dev to boot the expanded stack.
  3. Build out the service's domain with stackr add entity.