# `soap create`

Create a new SoapJS project.

Generated projects require Node.js `>=24.17.0` (Node 24 LTS or newer).
The generator writes `.nvmrc` with `24.17.0` so `nvm use` selects the supported runtime.

```bash
soap create users-api --skip-install
soap create users-api --install
soap create users-api --git-init --skip-install
soap create users-api -i
soap create users-api --preset express-postgres-api --skip-install
soap create users-api --db mysql --db sqlite --skip-install
soap create users-api --auth oauth --oauth-provider google --oauth-provider github --skip-install
soap create users-api --auth oauth --oauth-provider custom:acme --oauth-authorization-url https://auth.example.com/oauth/authorize --oauth-token-url https://auth.example.com/oauth/token --oauth-user-info-url https://auth.example.com/oauth/userinfo --skip-install
soap create users-api --controller-layout per-feature --skip-install
```

## Interactive Flow

```bash
soap create users-api -i
```

Prompts cover the supported MVP capabilities:

- framework
- architecture
- controller layout
- databases
- auth
- token delivery and PostgreSQL/MongoDB-backed auth/API-key storage
- OAuth provider presets, per-provider provisioning, and custom claim mapping
- messaging
- realtime
- telemetry (`logs`, `otel-noop`, `metrics`, `memory`)
- OpenAPI docs
- contracts
- Bruno API client
- API zones
- package manager
- dependency install intent
- git init intent

Before writing files, interactive mode prints a project summary and asks for confirmation.

Use `--yes` to skip the final confirmation:

```bash
soap create users-api -i --yes
```

## Presets

Available presets:

- `express-mongo-api`
- `express-postgres-api`
- `express-cqrs-kafka-api`
- `express-full-demo`

Examples:

```bash
soap create users-api --preset express-mongo-api --skip-install
soap create users-api -i --preset express-full-demo
```

In interactive mode, preset values become prompt defaults. Explicit CLI flags still override prompt answers and preset defaults.

## Notes

- Only `express` is currently supported.
- `--contracts zod` enables generated contracts backed by Zod.
- `--controller-layout per-route|per-feature` controls whether route controllers are generated as one controller per route or one controller per feature. The default is `per-route`.
- Auth projects use `@soapjs/soap-auth` 1.x recipe configs and the `@soapjs/soap-express/auth` router/middleware helpers.
- Local/OAuth includes JWT automatically; API-key-only generation stays JWT-free.
- `--auth-storage database` generates production-oriented accounts, identities, refresh sessions, API keys, database lifecycle hooks, DI, and management endpoints for PostgreSQL or MongoDB.
- `--auth-database postgres|mongo` selects the auth backend when both databases were selected; with one supported `--db`, it is inferred.
- OAuth provider presets are `google`, `github`, `facebook`, `discord`, `linkedin`, `twitter`, and `apple`; custom providers require authorization, token, and userinfo URLs.
- Security defaults are generated through soap-express security config. Auth projects include route-specific throttling for login, refresh, and OAuth callbacks.
- `--telemetry metrics` exposes `/metrics`; `--telemetry memory` exposes `/memory`. Minimal projects keep these monitoring endpoints disabled.
- Database capabilities include `mongo`, `postgres`, `mysql`, `sqlite`, and `redis`. Resource repositories are generated for Mongo and SQL adapters; Redis is infrastructure-only for now.
- `--install` runs the selected package manager after files are written. `--skip-install` always skips installation.
- `--git-init` runs `git init` after files are written. It does not commit or push.
- `--dry-run` prints the planned file count and planned writes.