# Base — Next.js (templates2)

A **ready-to-run** Next.js (App Router) base application. It is the shared core every Next.js
v2 case forks: authentication, roles, Prisma, mock payments and email, an admin shell, SEO,
i18n, observability, CI and a Docker image — all working on the first run.

> Not listed in the user catalog (`"catalog": false` in `.w4c/template.json`); it exists to be
> forked by cases such as `Store.Next` or `Saas.Next`.

## Quickstart

```bash
npm ci
cp .env.example .env          # SQLite + mock providers by default — no keys needed
npm run db:setup              # prisma db push + seed
npm run dev                   # http://localhost:3000
```

Demo accounts (seeded): `admin@example.com` (admin) and `user@example.com` (user) — password
`password`.

## Scripts

| Script | What it does |
|---|---|
| `npm run dev` | Dev server with HMR |
| `npm run build` / `npm start` | Production build / serve |
| `npm run lint` / `npm run typecheck` | ESLint / `tsc --noEmit` |
| `npm test` | Unit tests (Vitest) |
| `npm run test:e2e` | HTTP end-to-end smoke (server must be running) |
| `npm run db:setup` | `prisma db push` + seed |
| `npm run db:seed` | Seed only |

## What works out of the box

- **Auth & roles** — email + password, bcrypt, httpOnly cookie sessions (`Session` table), `user`
  and `admin` roles, server-side guards (`requireUser`, `requireAdmin`) and API authorization.
- **Payments** — a provider interface with a **mock provider that needs no keys** and activates the
  subscription immediately, plus a Stripe provider that turns on when `STRIPE_SECRET_KEY` is set.
  Webhooks are signature-checked and idempotent.
- **Email** — a log provider by default, Resend when `RESEND_API_KEY` is set.
- **Admin** — role-gated shell, overview dashboard, users table (role change / delete with
  confirmation) and an audit log.
- **SEO** — per-route metadata, OpenGraph, JSON-LD, `sitemap.xml`, `robots.txt`.
- **i18n** — English dictionary in `messages/en.json`, looked up via `t()`.
- **Observability** — `/api/health`, error boundary and loading/empty states.
- **Delivery** — multi-stage Dockerfile with a healthcheck, and CI running lint + typecheck + unit
  + build + e2e.

## Data model

`prisma/schema.prisma`: `User`, `Session`, `Subscription`, `AuditLog`. SQLite in development;
point `DATABASE_URL` at Postgres for production.

## Deployment

```bash
docker compose -f docker/docker-compose.yml up --build
```

## Quality

```bash
node ../templates2/qa.mjs Base.Next        # from the repo root: node templates2/qa.mjs Base.Next
```

The harness isolates a clean copy, then runs install → verify → test → build → boot → routes →
e2e → screenshot. See [`../CONTRACT.md`](../CONTRACT.md) for the Definition of Done.