Next.js 16 Architecture

Architecture patterns for Next.js 16 with Cache Components and feature-based organization.

Core Philosophy

1. Dynamic by default, cache what you choose - Use "use cache" explicitly
2. Fetch in smallest possible component - Don't prop-drill data
3. Keep everything static, stream only dynamic - Use Suspense for dynamic parts
4. Suspense boundaries high - Place in pages/layouts, not feature components

Quick Reference

Feature Folder Structure

features/{feature}/
├── components/
│   ├── server/       # Async data-fetching components
│   ├── client/       # 'use client' interactive components
│   └── skeletons/    # Loading states for Suspense
├── data/             # Database queries (SELECT, INSERT, UPDATE, DELETE)
├── actions/          # Server Actions ('use server' + cache invalidation)
├── types/            # TypeScript types (1 file = 1 type)
├── schemas/          # Zod schemas (1 file = 1 schema)
├── hooks/            # Client-side hooks
└── lib/              # Feature-specific utilities

File Naming

Cache Pattern

// Data file (SELECT with cache)
export async function getEntity(id: number) {
  "use cache";
  cacheTag(`entity-${id}`);
  cacheLife("hours");
  return await db.select()...
}

// Server Action (mutation + invalidation)
"use server";
export async function deleteEntityAction(id: number) {
  await deleteEntity(id);
  updateTag(`entity-${id}`);
}

Import Rules

• Always absolute: @/features/...
• Never relative: ../../../
• Direction: app/ → features/ → shared/

References

Load these based on what you need:

• Feature Structure - Complete feature organization, anatomy, rules
• Components - Server, Client, Skeletons, Compound UI patterns
• Data Layer - Cacheable queries, mutations, session handling
• Server Actions - Actions, cache invalidation, auth patterns
• Pages & Layouts - App router structure, route groups
• Internationalization - next-intl setup, flat keys, translations
• Shared Feature - Cross-cutting concerns, UI components
• Checklists - Code review and new feature checklists