Next.js Technology Stack

IMPORTANT NOTE: This document is not final; it is under review.

This document outlines standards and conventions for building web applications with Next.js.

Core Stack

• Framework: Next.js (v14+ app router)
• Language: TypeScript
• Monorepo: Turborepo with pnpm workspaces
• Bundler/Build: Next built-in toolchain; use Turborepo pipelines for caching/parallelism
• Styling: Tailwind CSS is required.
• UI Components: shadcn/ui is recommended.

Data Fetching & Caching

• Prefer Server Components and fetch with caching where possible.
• Use React Query (@tanstack/react-query) for client state that mirrors server cache.
• Co-locate data fetching with components; use route handlers for API endpoints.

Forms

• Use React Hook Form with Zod for schema validation.

API Routes

• Use Next.js Route Handlers under app/api/.../route.ts.
• Follow RESTful conventions and respond with typed payloads.

Testing

• Unit/Integration: Jest + Testing Library.
• E2E: Playwright or Cypress.

Naming Conventions

• Components: PascalCase.
• Hooks: use prefix with camelCase.
• Files/dirs: kebab-case.

Directory Structure (App Router)

src ├── app │ ├── (marketing)/ # Optional route groups │ ├── dashboard/ │ │ ├── page.tsx │ │ └── layout.tsx │ ├── api/ │ │ └── users/route.ts # Route handlers │ └── globals.css ├── components/ ├── features/ # Feature-based modules ├── lib/ # Utilities ├── providers/ └── types/

Monorepo with Turborepo

• Root managed with pnpm workspaces and Turborepo.
• Common packages under packages/ (e.g., ui, tsconfig, eslint-config).
• Apps under apps/ (e.g., web, admin).
• Sample turbo.json targets: build, lint, test, dev with caching and dependsOn.