Nextjs

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

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