nextjs-16-architecture

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.

Installation

$ npx skills add smithery/horuz-ai --skill nextjs-16-architecture

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Not declared

Cursor Not declared

Codex Not declared

GitHub Copilot Not declared

Windsurf Not declared

Gemini CLI Not declared

Cline Not declared

OpenCode Not declared

Package contents

Files included with this skill beyond the listing page.

skill md SKILL.md 3,568 B

docs SUMMARY.md 509 B

SKILL.md

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](references/feature-structure.md) - Complete feature organization, anatomy, rules
[Components](references/components.md) - Server, Client, Skeletons, Compound UI patterns
[Data Layer](references/data-layer.md) - Cacheable queries, mutations, session handling
[Server Actions](references/server-actions.md) - Actions, cache invalidation, auth patterns
[Pages & Layouts](references/pages-layouts.md) - App router structure, route groups
[Internationalization](references/i18n.md) - next-intl setup, flat keys, translations
[Shared Feature](references/shared-feature.md) - Cross-cutting concerns, UI components
[Checklists](references/checklists.md) - Code review and new feature checklists