forge-nextjs-mastery

id	FORGE-nextjs-mastery
name	FORGE-nextjs-mastery
version	1.0.0-2026.07.17
description	Next.js App Router engineering — server components, streaming, and edge patterns.
owner	A-FORGE
risk_tier	medium
floor_scope	["F1","F4","F12"]
autonomy_tier	T1

⚒️ Next.js Mastery — App Router Engineering

DITEMPA BUKAN DIBERI — Forged, Not Given.

Purpose

Build and maintain Next.js SPA surfaces with App Router discipline: server components first, ISR for content, API routes for organ bridges, strict client/server boundary.

When to Use

• Scaffolding or modifying a Next.js app in the federation (cockpit, organ surfaces)
• Routing decisions — parallel/intercepting routes, group layouts, loading/error boundaries
• Data fetching strategy — server component fetch vs SWR vs ISR
• API route design for organ proxying (/api/observatory/v1/*)

When NOT to Use

• Plain React without Next.js router — use react-spa-discipline
• Static site generation outside Vercel/Node — use Vite/build tool skill
• Backend logic that belongs in FastAPI or Express organ servers

Constitutional Floor Alignment

Floor	Application
F1 AMANAH	Keep page/route changes reversible; git stash before layout refactors
F2 TRUTH	generateStaticParams must match actual data; never fake revalidate values
F4 CLARITY	One data-fetching pattern per route group; no mixing server/client fetch
F7 HUMILITY	Default to loading.tsx + error.tsx on every route segment
F11 AUDIT	API routes log request origin; ISR revalidation events write to VAULT999
F13 SOVEREIGN	Public-facing routes reviewed by Arif before deploy

Commands & Patterns

# Create a new route segment under app router
# /root/AAA/src/app/<segment>/page.tsx (server component by default)
# /root/AAA/src/app/<segment>/loading.tsx
# /root/AAA/src/app/<segment>/error.tsx

# ISR pattern — revalidate every 60s, on-demand revalidation endpoint
export const revalidate = 60;
// POST /api/revalidate?secret=<token>&path=<path>

# API route pattern — proxy to organ
export async function GET(req: NextRequest) {
  const res = await fetch(`http://localhost:8088/mcp`, { ... });
  return NextResponse.json(await res.json());
}

# Server component fetch — direct, no hooks
async function Page() {
  const data = await fetch('http://localhost:8088/health').then(r => r.json());
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

Refusal Surface

• ❌ Client-side data fetching when server component can do it
• ❌ useEffect for API calls that belong in generateStaticParams or RSC
• ❌ Mixing Pages Router and App Router in the same surface
• ❌ Hardcoding organ ports in client components — use env proxy
• ❌ Skipping error/loading boundaries on user-facing routes