Template
refactor: rebuild template — Tailwind v4, Docker self-hosting, passkey auth
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
This commit is contained in:
Florian Wilde
@@ -1,67 +1,84 @@
|
||||
# AI Coding Starter Kit
|
||||
|
||||
> A Next.js template with an AI-powered development workflow using specialized skills for Requirements, Architecture, Frontend, Backend, QA, and Deployment.
|
||||
> 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
|
||||
## Tech Stack (binding for every new app)
|
||||
|
||||
- **Framework:** Next.js 16 (App Router), TypeScript
|
||||
- **Styling:** Tailwind CSS + shadcn/ui (copy-paste components)
|
||||
- **Backend:** Supabase (PostgreSQL + Auth + Storage) - optional
|
||||
- **Deployment:** Vercel
|
||||
- **Validation:** Zod + react-hook-form
|
||||
- **State:** React useState / Context API
|
||||
| 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 (Next.js App Router)
|
||||
app/ Pages and route handlers (App Router)
|
||||
api/health/ Liveness probe used by Docker + update script
|
||||
components/
|
||||
ui/ shadcn/ui components (NEVER recreate these)
|
||||
ui/ shadcn/ui — NEVER recreate these by hand
|
||||
hooks/ Custom React hooks
|
||||
lib/ Utilities (supabase.ts, utils.ts)
|
||||
features/ Feature specifications (PROJ-X-name.md)
|
||||
INDEX.md Feature status overview
|
||||
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
|
||||
production/ Production guides (Sentry, security, performance)
|
||||
DEPLOYMENT.md Docker Compose operations
|
||||
tests/ Playwright E2E specs
|
||||
scripts/update.sh Pull, rebuild, restart, roll back on failure
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
## Workflow
|
||||
|
||||
1. `/init` - Initialize the project: PRD + feature map (run once at the start)
|
||||
2. `/write-spec` - Create a full feature spec for one feature
|
||||
3. `/architecture` - Design tech architecture (PM-friendly, no code)
|
||||
4. `/frontend` - Build UI components (shadcn/ui first!)
|
||||
5. `/backend` - Build APIs, database, RLS policies
|
||||
6. `/qa` - Test against acceptance criteria + security audit
|
||||
7. `/deploy` - Deploy to Vercel + production-ready checks
|
||||
| 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 |
|
||||
|
||||
Use `/refine PROJ-X` at any point to revisit and improve an existing feature spec.
|
||||
`/refine PROJ-X` reopens an existing spec. `/help` reports where the project stands.
|
||||
|
||||
## Feature Tracking
|
||||
## Conventions
|
||||
|
||||
All features tracked in `features/INDEX.md`. Every skill reads it at start and updates it when done. Feature specs live in `features/PROJ-X-name.md`.
|
||||
- **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/`
|
||||
|
||||
## Key Conventions
|
||||
|
||||
- **Feature IDs:** PROJ-1, PROJ-2, etc. (sequential)
|
||||
- **Commits:** `feat(PROJ-X): description`, `fix(PROJ-X): description`
|
||||
- **Single Responsibility:** One feature per spec file
|
||||
- **shadcn/ui first:** NEVER create custom versions of installed shadcn components
|
||||
- **Human-in-the-loop:** All workflows have user approval checkpoints
|
||||
- **Tests:** Unit tests co-located next to source files (`useHook.test.ts` next to `useHook.ts`). E2E tests in `tests/`.
|
||||
|
||||
## Build & Test Commands
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
npm run dev # Development server (localhost:3000)
|
||||
npm run build # Production build
|
||||
npm run lint # ESLint
|
||||
npm run start # Production server
|
||||
npm test # Vitest unit/integration tests
|
||||
npm run test:e2e # Playwright E2E tests
|
||||
npm run test:all # Both test suites
|
||||
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
|
||||
@@ -71,3 +88,13 @@ npm run test:all # Both test suites
|
||||
## 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 -->
|
||||
|
||||
Reference in New Issue
Block a user