nextjs-typescript-engineer

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