Quick Start

This walkthrough takes you from nothing to a running, tested multi-service stack: you'll make your selections in the wizard, install and boot the project, then run both the per-service component tests and the cross-service end-to-end tests.

1. Generate the project

Run the CLI and answer the prompts. A typical run looks like this:

$ npx create-stackr@latest my-app

? Include a dedicated auth service? Yes
?   OAuth providers? Google, GitHub
?   Auth features? Email verification, Password reset
?   Include the Next.js admin dashboard? Yes
? First base service name? core
?   Platforms for core? Web
?   Event queue (BullMQ) for core? No
?   Auth middleware for core? standard
? Add another base service? No
? ORM? Drizzle
? AI coding tools? Claude Code, Cursor
? Package manager? npm

✔ Generated a 2-service monorepo (auth + core) with the context harness

That produces an auth service (with the admin dashboard) and a core base service with a Next.js web frontend — plus the context harness for the tools you selected. Every prompt is explained in Configuration. In a hurry? npx create-stackr@latest my-app --defaults skips the wizard.

2. Install dependencies & generate env

cd my-app
npm run setup

setup installs dependencies in every workspace, generates .env files with strong random credentials, and — if it finds stale Docker volumes from a previous run — offers to reset them.

3. Boot the stack

npm run docker:dev

Docker Compose brings up every service with its own database and Redis. For the selections above you get:

4. Run the component tests

Each service has its own Vitest suite that runs against an ephemeral Postgres + Redis (the component Docker profile), exercising the full route → service → repository path:

npm test

This walks every service and runs its component tests in isolation — a base service's tests mock the auth call, so they don't need the auth service running. See how it's built in Architecture → Testing.

5. Run the end-to-end tests

The e2e suite boots the whole stack (the e2e profile) and verifies the services work together — most importantly that a session minted by auth is accepted by core via cookie forwarding:

npm run test:e2e

It waits for every service to report healthy, then runs the cross-service checks.

What you have now

A running two-service monorepo with isolated databases, working auth, a web frontend, a green test suite, and an AI context harness wired in. From here:

• Extend it: add a service with stackr add service or a domain entity with stackr add entity.
• Understand it: read the Architecture section.
• Stay on-convention: point your AI agent (Claude Code, Cursor) at the repo — the harness already tells it the rules.