Frequently Asked Questions

How is stackr more than a scaffolding tool?

Two things. First, it generates a real multi-service architecture — isolated backends, databases, and an auth trust anchor — not a flat starter you outgrow. Second, it ships a context harness: files and rules that keep your project on-convention after generation, even when an AI agent writes the code. The scaffold is the starting point; the harness is what keeps it coherent.

What is the context harness?

A set of generated artifacts — nested AGENTS.md, a CLAUDE.md bridge, Cursor/Windsurf glob rules, Claude skills, ast-grep lint rules, and a post-edit hook — all derived from one source of truth. They deliver the project's conventions to your editor and agents (salience) and mechanically enforce the checkable ones (enforcement). See Why a Harness.

Why files instead of an MCP server?

Push delivery has no runtime dependency, nothing for the agent to forget to query, and can't go stale: the files are regenerated from stackr.config.json whenever the project shape changes. See Push, not pull.

Is it free? Can I use it commercially?

Yes — stackr is open source under the MIT license, free for commercial use.

Can I add services after the first scaffold?

Yes. stackr add service <name> wires a new isolated service into Docker Compose, the root .env, stackr.config.json, and the CI matrix — atomically.

Is Docker required?

For local development (docker:dev) and the test profiles, yes. The CLI itself runs without Docker, and you can run a single service's backend against a host-mode database if you prefer.

Which package manager should I use?

npm, yarn, and bun are all first-class — you pick at init and every script branches on your choice. bun is the recommended default.

Which ORM is the default?

Drizzle. Prisma is fully supported — choose it in the wizard. The ORM is locked monorepo-wide.

Can I build web-only or mobile-only?

Yes — platforms are per service. Enable web and/or mobile (or neither) on each base service. --no-auth produces a backend-only project with no auth service at all.

Why do base services forward cookies instead of verifying a token themselves?

So identity has exactly one owner. The auth service issues httpOnly cookies and is the only place that validates them; base services ask it /api/auth/get-session rather than trusting a token a client could forge. See Cross-Service Auth.

Why doesn't Apple Sign-In work on localhost?

Apple requires HTTPS redirect URIs. Use a tunnel (e.g. ngrok) for local development, or test it on a staging host with a valid certificate.

How do I add a new backend feature the "right" way?

Use stackr add entity for a domain slice — it generates the schema, repository, and service together and follows every backend convention. For HTTP, add a thin route that imports the generated TypeBox schema.