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 utilities
File 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