Template
Florian Wilde
b0c4e9e9b9
Toolchain fixes (all previously broken): - npm run lint: next lint was removed in Next 16 -> eslint with flat config - .eslintrc.json was ignored by ESLint 9 -> eslint.config.mjs - npm test / test:e2e exited 1 with no tests -> passWithNoTests - Vitest scanned tests/ and would have run Playwright specs -> scoped to src/ - Playwright targeted Mobile Safari while docs installed only chromium - reuseExistingServer silently tested a foreign server on :3000 -> E2E_PORT - 11 high-severity vulns -> npm audit fix - deny rule Read(**/.env*) also blocked .env.example -> precise patterns Stack changes: - Tailwind v3 -> v4 (CSS-first, no tailwind.config.ts, tw-animate-css) - shadcn regenerated for v4; 33 components -> 6 core, bundled radix-ui - Supabase removed entirely; data layer is now chosen per project - Vercel removed; Docker Compose self-hosting with scripts/update.sh - Better Auth + passkey plugin as the binding auth standard - ThemeProvider and Sonner mounted; dark mode and toasts now actually work Workflow system: - Sub-agents wired: /frontend, /backend, /qa delegate to .claude/agents - Checklists folded into their SKILL.md; one file per skill - Rules rewritten: DB-agnostic backend, passkey security, v4 frontend - Spec language settled as German, skill instructions English
101 lines
4.5 KiB
Markdown
101 lines
4.5 KiB
Markdown
# AI Coding Starter Kit
|
|
|
|
> Next.js template with an AI-driven development workflow. Skills cover Requirements,
|
|
> Architecture, Frontend, Backend, QA and Deployment. Every phase writes its result
|
|
> into the feature spec, so state lives in files rather than in the conversation.
|
|
|
|
## Tech Stack (binding for every new app)
|
|
|
|
| Layer | Choice | Notes |
|
|
|-------|--------|-------|
|
|
| Framework | Next.js 16, App Router | React 19, Server Components by default |
|
|
| Language | TypeScript, `strict` | `@/*` maps to `src/*` |
|
|
| Styling | Tailwind CSS v4 | CSS-first config in `src/app/globals.css`. **There is no `tailwind.config.ts`** — theme tokens live in `@theme inline`. |
|
|
| Components | shadcn/ui (`new-york`) | 6 pre-installed. Add more with `npx shadcn@latest add <name> --yes`. Never hand-write an equivalent. |
|
|
| Icons | lucide-react | |
|
|
| Forms | react-hook-form + Zod | Zod schema is the single source of truth for a form's validation |
|
|
| Notifications | sonner | Mounted in `layout.tsx`. The deprecated shadcn `toast` is deliberately absent. |
|
|
| Theming | next-themes | `attribute="class"`, dark mode via `.dark` |
|
|
| Auth | Better Auth + passkey plugin | Only when the project needs auth. Passkeys are the primary method — see `.claude/rules/security.md`. |
|
|
| Data layer | **decided per project** | The template ships none. `/architecture` picks and documents it. |
|
|
| Tests | Vitest (unit) + Playwright (E2E) | Vitest only scans `src/`, Playwright only `tests/` |
|
|
| Deployment | Docker Compose, self-hosted | App container only; TLS/routing via a reverse proxy on the host |
|
|
|
|
Deliberately **not** part of this template: Supabase, Vercel, any preselected ORM
|
|
or database. Do not reintroduce them without the user asking.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
src/
|
|
app/ Pages and route handlers (App Router)
|
|
api/health/ Liveness probe used by Docker + update script
|
|
components/
|
|
ui/ shadcn/ui — NEVER recreate these by hand
|
|
hooks/ Custom React hooks
|
|
lib/utils.ts cn() helper
|
|
features/ One spec per feature: PROJ-X-name.md
|
|
INDEX.md Status of every feature — read this first
|
|
docs/
|
|
PRD.md Product Requirements Document
|
|
DEPLOYMENT.md Docker Compose operations
|
|
tests/ Playwright E2E specs
|
|
scripts/update.sh Pull, rebuild, restart, roll back on failure
|
|
```
|
|
|
|
## Workflow
|
|
|
|
| Step | Command | Produces |
|
|
|------|---------|----------|
|
|
| 1 | `/init` | PRD + feature map (once per project) |
|
|
| 2 | `/write-spec` | Full spec for one feature |
|
|
| 3 | `/architecture` | Tech design inside the spec |
|
|
| 4 | `/frontend` | UI components |
|
|
| 5 | `/backend` | APIs, data layer, auth |
|
|
| 6 | `/qa` | Test results inside the spec |
|
|
| 7 | `/deploy` | Live Docker Compose stack |
|
|
|
|
`/refine PROJ-X` reopens an existing spec. `/help` reports where the project stands.
|
|
|
|
## Conventions
|
|
|
|
- **Feature IDs:** `PROJ-1`, `PROJ-2`, … sequential, tracked in `features/INDEX.md`
|
|
- **Commits:** `type(PROJ-X): description` — feat, fix, refactor, test, docs, deploy, chore
|
|
- **One feature per spec file** — never combine independent functionality
|
|
- **Spec language:** German (PRD, specs, acceptance criteria). Code, comments and
|
|
skill instructions stay English.
|
|
- **Human-in-the-loop:** every skill ends with a user approval checkpoint
|
|
- **Tests:** unit tests co-located (`useThing.test.ts` beside `useThing.ts`), E2E in `tests/`
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm run dev # Dev server on :3000
|
|
npm run build # Production build (standalone output)
|
|
npm run lint # ESLint (flat config)
|
|
npm run typecheck # tsc --noEmit
|
|
npm test # Vitest
|
|
npm run test:e2e # Playwright
|
|
npm run test:all # Both
|
|
npm run docker:up # Build and start the Compose stack
|
|
./scripts/update.sh # Deploy latest commit on the server
|
|
```
|
|
|
|
## Product Context
|
|
|
|
@docs/PRD.md
|
|
|
|
## Feature Overview
|
|
|
|
@features/INDEX.md
|
|
|
|
<!-- BEGIN:nextjs-agent-rules -->
|
|
|
|
# This is NOT the Next.js you know
|
|
|
|
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
|
|
|
|
This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
|
|
|
|
<!-- END:nextjs-agent-rules -->
|