Configuration

Running create-stackr always prompts for the shape of your monorepo — there are no presets to memorize. This page documents every prompt, the flags that skip them, and what the CLI generates.

The interactive wizard

npx create-stackr@latest my-app

The wizard asks, in order:

1. Project name — directory and package name.
2. Include a dedicated auth service? (default: yes) — the trust anchor. If you say yes, you're then asked for:
   • OAuth providers — Google, Apple, GitHub (any combination).
   • Auth features — email verification, password reset (default on), and two-factor authentication.
   • Additional user fields — extra columns on the user record.
   • Include the Next.js admin dashboard? (default: yes) — a ready-made UI to manage users and roles.
3. Base service(s) — for each one:
   • Name (default: core).
   • Platforms — add a Next.js web frontend and/or an Expo mobile app (both optional).
   • Event queue — a BullMQ + Redis worker (default: off).
   • Auth middleware flavor (when an auth service exists) — standard, role-gated (you supply the allowed roles), flexible, or none. See Cross-Service Auth.
   • Add another base service? — loops until you're done.
4. ORM — Drizzle (default) or Prisma, locked across the whole monorepo.
5. AI coding tools — Claude Code, Codex, Cursor, Windsurf. Your selection decides which harness artifacts are generated (see The Context Harness).
6. Package manager — npm, yarn, or bun.

Non-interactive generation

Pass --defaults to skip every prompt and generate the default shape: Drizzle, an auth service with the admin dashboard, and one core base service.

npx create-stackr@latest my-app --defaults

You can shape a non-interactive run further with flags:

# Default config plus two extra services and a CI workflow
npx create-stackr@latest my-app --defaults --with-services scout,manage --ci-workflow

# Backend-only project, no auth, base service named "api"
npx create-stackr@latest my-app --no-auth --service-name api

Generated environment & credentials

stackr generates .env files (root and per-service backend/.env) at init, filled with strong random credentials — a 24-character database password and a 64-character hex BETTER_AUTH_SECRET. A committed .env.example holds placeholders.

# Generated, never committed
POSTGRES_PASSWORD=<24-char random>
BETTER_AUTH_SECRET=<64 hex chars>
AUTH_SERVICE_URL=http://auth:8888

OAuth client IDs and secrets (Google, Apple, GitHub) go into the auth service's environment — they are placeholders in .env.example until you fill them in. See Configuring OAuth & Third-Party Integrations for where every third-party value (OAuth, SMTP, and the mobile SDKs) lives and how to obtain it, plus npx stackr config to report what's still unconfigured.

Ports

Ports are allocated deterministically so generated scripts, Docker Compose, and CI are reproducible:

stackr.config.json

The generated stackr.config.json is the source of truth for the monorepo's shape — the service list, ORM, package manager, ports, and any pending migrations. The stackr CLI reads and updates it.