Next.js 16 Architecture
Architecture patterns for Next.js 16 with Cache Components and feature-based organization.
Core Philosophy
- Dynamic by default, cache what you choose - Use
"use cache"explicitly - Fetch in smallest possible component - Don't prop-drill data
- Keep everything static, stream only dynamic - Use Suspense for dynamic parts
- 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 utilitiesFile Naming
| Type | Pattern | Example |
|---|---|---|
| Server component | kebab-case.tsx | agent-header.tsx |
| Client component | kebab-case.tsx | login-form.tsx |
| Skeleton | {name}-skeleton.tsx | agent-header-skeleton.tsx |
| GET query | get-{entity}.ts | get-agent.ts |
| GET multiple | get-{entities}.ts | get-agents.ts |
| CREATE | create-{entity}.ts | create-agent.ts |
| DELETE | delete-{entity}.ts | delete-agent.ts |
| Server Action | {verb}-{entity}-action.ts | delete-agent-action.ts |
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