name

nextjs

description

Provides Next.js project architecture expertise and implementation patterns. Enforces BFF (Backend for Frontend) pattern, Server Components strategy, and data fetching policies. Specializes in App Router architecture, Server Actions, streaming SSR, incremental static regeneration, and route handlers. Ensures optimal performance through proper component boundaries and caching strategies. Use when: developing Next.js applications, implementing App Router patterns, creating Server Components and Client Components, designing Server Actions for mutations, implementing data fetching with fetch API, configuring BFF architecture, optimizing page performance with streaming and suspense, handling routing and navigation, implementing middleware, or setting up API route handlers.

Next.js Project Architecture Rules

Scope: Project-specific policies and architecture decisions only.

Version: Next.js 15.5+ with App Router

1. BFF Architecture (Mandatory)

Absolute Rules

Next.js serves ONLY as a thin Backend for Frontend (BFF) layer:

Browser ↔ Next.js Server ↔ Backend API ↔ Database

NEVER:

❌ Direct database access from Next.js (no Prisma, no ORMs)
❌ Business logic implementation in Next.js
❌ Data validation beyond input sanitization

ALWAYS:

✅ All business logic in separate backend service
✅ All database operations via backend API
✅ Next.js for: SSR/SSG, API aggregation, session management, caching

2. Component Strategy (Enforced)

Server Components First

Rule: Default to Server Components. 'use client' only at leaf nodes.

Client Component allowed for:

Event handlers (onClick, onChange)
Browser APIs (localStorage, window)
React hooks (useState, useEffect)

Violation: Client Component wrapping Server Components

3. Rendering Strategy (Explicit Declaration Required)

Mandatory Export

Every page MUST explicitly declare rendering intent:

// Required - choose one:
export const dynamic = "force-static"; // SSG
export const dynamic = "force-dynamic"; // SSR
export const revalidate = 3600; // ISR

No implicit rendering. Always be explicit about caching behavior.

4. Data Fetching (Server Actions vs API Routes)

Server Actions (Default for Internal Operations)

Use for:

Form submissions
Data mutations
Internal Next.js operations

Location: app/actions/*.ts or inline with 'use server'

API Routes (External Integration ONLY)

Use for:

Webhooks (Stripe, GitHub, etc.)
OAuth callbacks
Mobile app endpoints
Third-party service integrations

Location: app/api/*/route.ts

NEVER: API routes for internal Next.js-to-Next.js communication

5. Caching Policy (Explicit Intent Required)

Mandatory Cache Declaration

All fetch calls MUST explicitly specify caching:

// Required - choose one:
fetch(url, { next: { revalidate: 3600 } }); // Time-based
fetch(url, { cache: "no-store" }); // Dynamic

Use React cache() to prevent duplicate requests within render cycle.

No implicit caching. Always declare intent.

6. Export Rules (Next.js App Router Exception)

Default Export Exception

Next.js App Router REQUIRES default exports for route files. This overrides the React skill's "no default export" rule.

Required default exports for:

page.tsx - Route page components
layout.tsx - Layout components
error.tsx - Error boundary
loading.tsx - Loading UI
not-found.tsx - 404 page

Allowed pattern:

// Named export + default export for Next.js compatibility
export const MyPage = () => { ... };
export default MyPage;

All other components: Follow React skill (named exports only)

Critical Violations

Direct DB access from Next.js → Architecture violation
API Routes for internal mutations → Use Server Actions
Missing rendering strategy declaration → Add explicit export
Client Component not at leaf → Move 'use client' down
Implicit caching → Add explicit cache declaration
Backend not separated → Mandatory separate service