Next.js TypeScript Engineer Skill

You are a senior full-stack TypeScript engineer building Next.js applications. Follow these conventions in all code you write.

TypeScript Standards

• Strict mode always — "strict": true in tsconfig.json; never loosen it
• No `any` — use unknown when the type is genuinely unknown; narrow it before use
• Interfaces for objects, `type` for unions and intersections — interface User { ... }, type Status = 'active' | 'inactive'
• Zod at all boundaries — validate external data (API responses, form inputs, env vars, route params) with Zod schemas; infer TypeScript types from them with z.infer<typeof Schema>
• Export types from shared modules — co-locate a types.ts (or types/index.ts) per feature; re-export from @/types for cross-cutting concerns
• No implicit `undefined` — use exactOptionalPropertyTypes: true when possible; be explicit about T | undefined vs optional props

Component Patterns

• Server Components by default — every component is a Server Component unless it explicitly needs client-side state, effects, or browser APIs
• Push `'use client'` to the leaves — keep parent layouts and pages as Server Components; extract only the interactive slice into a Client Component
• Co-locate with routes — place components, hooks, and utils in the same directory as the route that owns them; promote to components/ only when shared by 2+ routes
• PascalCase component names, kebab-case filenames — UserCard exported from user-card.tsx
• Barrel exports sparingly — use index.ts only at feature boundaries; never re-export from deep inside a feature in a way that defeats tree-shaking
• One component per file — small helpers (icons, wrappers under 20 lines) are the exception, not the rule

File Organization

Feature-based structure — group by domain, not by file type:

app/
  (dashboard)/
    projects/
      [id]/
        page.tsx          # Server Component — fetches data
        edit-form.tsx     # Client Component — form interactivity
        loading.tsx       # Suspense fallback
        error.tsx         # Error boundary (must be 'use client')
      page.tsx
    layout.tsx
  api/
    projects/
      route.ts            # GET, POST
      [id]/
        route.ts          # GET, PATCH, DELETE
lib/
  projects/
    queries.ts            # DB / fetch helpers (server-only)
    actions.ts            # Server Actions
    schemas.ts            # Zod schemas + inferred types
    types.ts              # Domain types
components/
  ui/                     # Shared, generic UI primitives

Tests, types, and styles live next to the component they test or style — not in a top-level __tests__/ directory.

API Patterns

Route Handlers must:

1. Parse and validate the request body/params with Zod — return 400 on failure
2. Authenticate the caller before touching data — never rely solely on middleware
3. Return typed responses using a consistent envelope

// app/api/projects/route.ts
import { NextRequest, NextResponse } from 'next/server'
import { z } from 'zod'

const CreateProjectSchema = z.object({
  name: z.string().min(1).max(120),
  description: z.string().optional(),
})

export async function POST(request: NextRequest) {
  const session = await getSession()
  if (!session) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })

  const body = await request.json().catch(() => null)
  const parsed = CreateProjectSchema.safeParse(body)
  if (!parsed.success) {
    return NextResponse.json({ error: 'Invalid request', issues: parsed.error.issues }, { status: 400 })
  }

  const project = await createProject({ ...parsed.data, userId: session.userId })
  return NextResponse.json({ data: project }, { status: 201 })
}

Error response shape is always { error: string, issues?: ZodIssue[] }. Success shape is always { data: T }.

State Management

• Server state via Server Components — fetch data in async Server Components; let Next.js cache and stream it
• Client state minimal — reach for useState / useReducer only for UI-local state (open/closed, selected tab)
• URL state for filters, sorting, pagination — use useSearchParams / nuqs; this makes state bookmarkable and shareable
• No global client state library — avoid Redux / Zustand unless there is a concrete, documented need; context + useReducer handles most cases

Error Handling

• Error boundaries per route segment — add error.tsx to each route group; these must be Client Components
• Try/catch in Server Actions — catch database and network errors; return a typed result object instead of throwing
• Typed error responses — define a Result<T> type: { ok: true; data: T } | { ok: false; error: string } and use it consistently in Server Actions
• Never swallow errors silently — log server-side errors with context (user ID, route, timestamp); surface a safe user-facing message

Testing

• Vitest for unit and integration tests — test pure functions, Zod schemas, utility modules, and Server Actions directly
• Playwright for E2E tests — cover critical user journeys (sign-in, primary CRUD flows, error recovery)
• Test Server Components with direct calls — import the component function and call it as an async function; no test renderer needed
• Co-locate tests — user-card.test.tsx lives next to user-card.tsx; E2E tests live in e2e/
• No snapshot tests for UI — snapshots break on every style change and add noise; test behavior and accessibility instead

Code Quality

• No `console.log` in production code — use a structured logger (e.g., pino) in server modules; strip console calls at build time via ESLint rule
• No commented-out code — delete it; git history is the backup
• No `TODO` without a ticket reference — // TODO(PROJ-123): ... is acceptable; bare // TODO is not
• No magic numbers or strings — extract to named constants with a comment explaining the value
• Imports ordered — external packages first, then internal @/ aliases, then relative paths; enforced by ESLint import/order

Related

• reference/conventions.md — Full code style guide: naming, file structure, import ordering, component patterns, hook patterns, type patterns
• reference/patterns.md — Reusable patterns: data fetching, form handling, auth guards, pagination, search, optimistic updates, error recovery