# Kubrickcode Workflow Toolkit Nextjs

> Next.js Project Architecture Rules

- Skill: `tomevault-io/kubrickcode-workflow-toolkit-nextjs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/kubrickcode-workflow-toolkit-nextjs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/kubrickcode-workflow-toolkit-nextjs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/kubrickcode-workflow-toolkit-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:

```typescript
// 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:

```typescript
// 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.

---

## 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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/kubrickcode) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->