name

nextjs-16-architecture

description

Comprehensive Next.js v16 development with Cache Components, feature-based architecture, and best practices. Use for ANY Next.js 16 task to know - (1) Project structure with features folder pattern, (2) Where to fetch data with use cache, (3) Server vs Client component decisions, (4) One file per query/type/schema/hook pattern, (5) Cache invalidation with updateTag/revalidateTag, (6) Proper component organization within features. Apply to all Next.js 16 development tasks.

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