app-starter

An AWS-first pnpm monorepo template for typed Postgres + Lambda/Express API + React/Vite frontend.

The default repo standard is:

• TypeScript everywhere
• PostgreSQL functions for every read and write
• AWS-native deployment on Linux
• scales-to-zero API runtime via Lambda + API Gateway
• Cognito as the default auth mode

Optional non-default paths are preserved under targets/, including the old IIS hosting flow.

Packages

packages/
  api/        @app/api        Express app factory with local and Lambda shells
  db/         @app/db         pg client, SQL migrations, repositories, schema snapshot
  frontend/   @app/frontend   React/Vite SPA with AppForm and DataTable
  infra/      @app/infra      reference CDK stack for AWS deploys
  types/      @app/types      shared wire types and zod schemas

Quick start

pnpm install
pnpm configure
pnpm dev:db
pnpm migrate
pnpm dev:api
pnpm dev:frontend

The configure script is now AWS-first. It asks for:

• deployment target: aws (default) or optional iis
• auth mode: cognito (default), none, or optional local

Useful non-interactive example:

pnpm configure --target=aws --auth=cognito

Commands

pnpm build
pnpm typecheck
pnpm lint
pnpm format

pnpm dev:db
pnpm migrate
pnpm db:test

pnpm infra:synth
pnpm infra:deploy

pnpm target:iis:publish-local   # optional Windows/IIS target only

Deployment model

Default

• API: Lambda behind API Gateway
• frontend: S3 + CloudFront
• auth: Cognito
• infra: CDK in packages/infra
• CI/CD: .github/workflows/aws-deploy.yml

The reference workflow deploys infrastructure with GitHub OIDC, builds the SPA with VITE_API_URL=/api, uploads assets to S3, and invalidates CloudFront.

Optional IIS target

Windows/IIS assets were removed from the main template surface and preserved under targets/iis/.

See targets/iis/README.md when a project genuinely needs that path.

Data access

@app/db is now function-only by construction.

• writes call usp_* functions
• reads call fn_* functions
• repos use a small pg helper instead of a query builder
• migrations are SQL files in packages/db/src/migrations/*.sql
• the schema snapshot in packages/db/schema/ must stay in sync with migrations

Auth modes

• cognito: default AWS path
• none: explicit dev-only shortcut
• local: optional cookie/JWT mode retained for self-contained projects

The old IIS header strategy is preserved only in the optional IIS target.