nextjs-16-architecture

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

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

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