nextjs-16-architecture

horuz-ai's avatarfrom horuz-ai

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.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 22, 2025
[Architecture Design]

When & Why to Use This Skill

This Claude skill provides a comprehensive architectural framework for Next.js 16 development, emphasizing feature-based organization and the latest Cache Components. It streamlines the creation of scalable web applications by providing standardized patterns for data fetching, server/client component separation, and modular project structures, ensuring high performance and maintainability.

Use Cases

  • Project Initialization: Setting up a scalable Next.js 16 project structure using the 'features' folder pattern to avoid monolithic directory bloat.
  • Performance Optimization: Implementing granular data caching using the 'use cache' directive and managing invalidation with updateTag/revalidateTag.
  • Component Strategy: Making informed decisions on Server vs. Client component placement to minimize client-side bundles and improve SEO.
  • Code Standardization: Enforcing consistent file naming conventions and absolute import rules across large development teams.
  • Feature Modularization: Organizing business logic, database queries, and UI components into self-contained feature modules for better code reusability.
namenextjs-16-architecture
description>

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: