Next.js Coding Standards Skill

Auto-Load Trigger: Presence of next.config.* or "next" in package.json

When to Use

Starting a new Next.js project
Before any TypeScript/React file edit
When context seems lost mid-session
After /agent_reset or /vibe-primeAgent

🛑 Verification Protocol (MANDATORY)

After Every TypeScript/TSX File Edit

npx tsc --noEmit

If this fails:

DO NOT proceed to next file
Fix the type error immediately
Re-run until it passes
Only then continue

Before Any Handoff

python scripts/vibe-verify.py

All checks must pass before claiming "done."

The Blueprint & Build Protocol

Phase 1: Blueprint (Before Coding)

Check docs/features/ for existing patterns
Create/update docs/features/FeatureName.md
Wait for approval before coding

Phase 2: Build (Implementation)

Announce which FR-XXX you're implementing
Reference the corresponding issue in docs/issues/
Implement one step at a time
tsc --noEmit after every file
Mark acceptance criteria as complete

Phase 3: Finalization

Run full verification (vibe-verify.py)
Update issue file with completion status
Generate handoff summary

Full-Stack Type Safety

The AI reliability secret: TypeScript tells you when you broke something.

Core Principle

If you change the backend, the frontend MUST type-check. If type-check fails:

The change broke something
Fix it before moving on
Never ignore type errors

Stack Alignment

Server Components fetch data → types flow to client
API routes return typed responses → frontend consumes them
Prisma schema changes → regenerate client → type-check

Next.js App Router Rules

Server Components Default — No 'use client' unless required
Client Components Sparingly — Only for interactivity, hooks, browser APIs
Data Fetching — In async Server Components, not useEffect
Route Handlers — All API in app/api/.../route.ts
Caching — Be explicit: { cache: 'no-store' } or revalidate = N

File Structure (Feature-Sliced)

src/
├── app/                    # Next.js App Router pages
├── features/               # Business domains
│   └── [FeatureName]/
│       ├── components/     # Feature-specific components
│       ├── hooks/          # Feature-specific hooks
│       └── *.service.ts    # Business logic
├── components/
│   ├── ui/                 # Reusable UI (Button, Card)
│   └── layout/             # Layout components
├── lib/                    # Utilities, clients
└── scripts/                # Automation (vibe-verify.py)

Component Rules

200-Line Limit — Refactor if exceeded
Single Responsibility — One thing per component
Props Interface — Always use TypeScript interfaces
Custom Hooks — Extract stateful logic into use* hooks

Styling (Tailwind v4)

Why Tailwind for AI Reliability: Tailwind colocates styles with UI in a single file. Unlike separate .css files, AI agents see the complete context (logic + styles + structure) without jumping between files. This dramatically reduces hallucinations and context fragmentation.

@import "tailwindcss";

@theme {
  --color-background: #ffffff;
  --color-foreground: #0b1221;
  --color-border: #e5e7eb;
}

@theme .dark {
  --color-background: #0b1221;
  --color-foreground: #e5e7eb;
}

Use @theme tokens, not tailwind.config extensions
Utility-first, no custom CSS files
Dark mode via .dark class on <html>

Backend Rules

Service Layer Pattern

Route Handlers = Controllers (parse request, return response)
Services = Business logic (DB queries, calculations)

Validation

import { z } from 'zod';

const schema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
});

All inputs validated with Zod. No exceptions.

Templates Available

This skill provides templates in templates/:

Coding_Guidelines.md — Copy to docs/Coding_Guidelines.md
Issue_Template.md — Format for FR issues

Quick Reference

Command	When
`npx tsc --noEmit`	After every TS/TSX edit
`python scripts/vibe-verify.py`	Before handoff
`npm run lint`	Check code style
`npm run build`	Verify production build

Recovery Protocol

If you break something:

git status                    # See changed files
git diff                      # See what changed
git checkout -- <file>        # Revert specific file
git stash                     # Save and revert all

nextjs-standards