Nextjs Idioms

Next.js Idioms and Patterns

Next.js (15+) rewards App Router, Server Components, and Server Actions. Idiomatic Next.js = server-first, streaming, edge-ready. Push logic to the server, keep the client thin.

Scope: Next.js-specific patterns only. For React: @.agents/skills/react-idioms/SKILL.md. For TypeScript: @.agents/skills/typescript-idioms/SKILL.md. For project layout: references/project-structure.md.

Loading guard: This skill assumes the Next.js App Router (Next.js 15+, app/ directory). For Pages Router (pages/) legacy code, most React idioms still apply but App-Router-specific sections (RSC, Server Actions, parallel/intercepting routes, 'use cache') do not. Co-load @.agents/skills/react-idioms/SKILL.md for client-component patterns.

When to Load References

Load these before writing code in the matching context — not after.

---

Server vs Client Component Decision Tree

1. Keep Server Component (default) when: fetching data, accessing DB/secrets, using heavy deps, or rendering static/cacheable content.
2. Add 'use client' only when: using hooks (useState, useEffect), attaching event handlers, calling browser APIs (window, localStorage), or wrapping third-party client libs.
3. Composition pattern — server parent fetches, client child handles interactivity:

   // app/tasks/page.tsx (Server)
   export default async function TasksPage() {
     const tasks = await getTasks();
     return <TaskBoard tasks={tasks} />;   // Client component for drag-and-drop
   }
   
   // features/task/components/task-board.tsx ('use client')
   export function TaskBoard({ tasks }: { tasks: Task[] }) {
     const [sorted, setSorted] = useState(tasks);
     return <DndContext>...</DndContext>;
   }

4. Push 'use client' as deep as possible — never mark an entire page as client:

   // ❌ 'use client' at page level loses all server benefits
   // ✅ Only wrap the interactive leaf:
   export default async function TasksPage() {
     const tasks = await getTasks();
     return (
       <>
         <TaskStats count={tasks.length} />   {/* Server */}
         <TaskFilterBar />                     {/* Client — has state */}
       </>
     );
   }

---

App Router (Default)

1. Server Components by default — add 'use client' only per the decision tree above.
2. Layouts for shared UI — never duplicate headers/sidebars.
3. Loading/Error boundaries per route segment:

   app/tasks/
   ├── page.tsx        # Server Component
   ├── loading.tsx     # Suspense fallback
   ├── error.tsx       # Error boundary ('use client')
   └── layout.tsx      # Shared layout

4. Route groups for organization without URL impact:

   app/
   ├── (auth)/login/page.tsx          # /login
   ├── (auth)/register/page.tsx       # /register
   └── (dashboard)/
       ├── layout.tsx                 # Shared dashboard layout
       ├── tasks/page.tsx             # /tasks
       └── settings/page.tsx          # /settings

---

Parallel & Intercepting Routes

1. @slot parallel routes — render multiple pages simultaneously in the same layout:

   app/(dashboard)/
   ├── layout.tsx                          # Receives { children, modal }
   ├── @modal/default.tsx                  # Required: null fallback
   ├── @modal/(.)tasks/[id]/page.tsx       # Intercepting route → modal
   ├── tasks/page.tsx                      # Main content
   └── tasks/[id]/page.tsx                 # Full page (direct nav)

2. Layout consumes parallel slots as props:

   export default function DashboardLayout({
     children, modal,
   }: {
     children: React.ReactNode; modal: React.ReactNode;
   }) {
     return <>{children}{modal}</>;
   }

3. default.tsx is required for every @slot — returns null when no active match.
4. Intercepting conventions: (.) same level, (..) one level up, (...) from root.

---

Data Fetching

1. Server Components fetch data directly — no useEffect:

   export default async function TasksPage() {
     const tasks = await db.tasks.findMany();
     return <TaskList tasks={tasks} />;
   }

2. Server Actions for mutations:

   'use server';
   import { revalidatePath } from 'next/cache';
   import { redirect } from 'next/navigation';
   
   export async function createTask(formData: FormData) {
     const title = formData.get('title');
     if (!title || typeof title !== 'string') return { error: 'Title is required' };
     await db.tasks.create({ data: { title } });
     revalidatePath('/tasks');
     redirect('/tasks');
   }

3. Parallel data fetching — never sequential await:

   const [user, tasks, stats] = await Promise.all([getUser(), getTasks(), getStats()]);

---

Caching Strategy

1. fetch cache options — Next.js extends fetch:

   await fetch(url, { cache: 'force-cache' });                // Cached indefinitely
   await fetch(url, { cache: 'no-store' });                   // Fresh every request
   await fetch(url, { next: { revalidate: 3600 } });          // Time-based ISR
   await fetch(url, { next: { tags: ['tasks'] } });           // Tag-based invalidation

2. 'use cache' directive for non-fetch data (DB queries, computations — Next.js 15+):

   'use cache';
   import { cacheLife, cacheTag } from 'next/cache';
   
   export async function getCachedTasks(userId: string) {
     cacheLife('minutes');               // Built-in profile: 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'max'
     cacheTag('tasks', `user-${userId}`);
     return db.tasks.findMany({ where: { userId } });
   }

   Legacy: unstable_cache (deprecated in Next.js 15+) works the same way but is being replaced by 'use cache'.

3. Per-route segment config:

   export const revalidate = 60;            // ISR every 60s
   export const dynamic = 'force-dynamic';  // Always fresh

4. On-demand revalidation in Server Actions:

   'use server';
   export async function updateTask(id: string, data: TaskUpdate) {
     await db.tasks.update({ where: { id }, data });
     revalidateTag('tasks');       // Invalidate tagged fetches
     revalidatePath('/tasks');     // Rebuild the page
   }

5. Decision tree: Static → force-cache. User-specific → no-store. Semi-dynamic → revalidate: N. After mutation → revalidateTag/revalidatePath.

---

API Route Handlers

1. Export named functions per HTTP method — validate with Zod, never trust raw input:

   // app/api/tasks/route.ts
   import { NextRequest, NextResponse } from 'next/server';
   import { z } from 'zod';
   
   const createTaskSchema = z.object({
     title: z.string().min(1).max(200),
     priority: z.enum(['low', 'medium', 'high']).default('medium'),
   });
   
   export async function GET(request: NextRequest) {
     const tasks = await db.tasks.findMany();
     return NextResponse.json(tasks);
   }
   
   export async function POST(request: NextRequest) {
     const parsed = createTaskSchema.safeParse(await request.json());
     if (!parsed.success) {
       return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
     }
     const task = await db.tasks.create({ data: parsed.data });
     return NextResponse.json(task, { status: 201 });
   }

2. Dynamic route params (Next.js 15+ — params is a Promise):

   // app/api/tasks/[id]/route.ts
   export async function GET(
     request: NextRequest,
     { params }: { params: Promise<{ id: string }> }
   ) {
     const { id } = await params;
     const task = await db.tasks.findUnique({ where: { id } });
     if (!task) return NextResponse.json({ error: 'Not found' }, { status: 404 });
     return NextResponse.json(task);
   }

3. Streaming responses for large datasets:

   export async function GET() {
     const stream = new ReadableStream({
       async start(controller) {
         for await (const chunk of db.tasks.stream()) {
           controller.enqueue(new TextEncoder().encode(JSON.stringify(chunk) + '\n'));
         }
         controller.close();
       },
     });
     return new Response(stream, { headers: { 'Content-Type': 'application/x-ndjson' } });
   }

---

Middleware

1. middleware.ts at project root (or src/middleware.ts):

   import { NextResponse } from 'next/server';
   import type { NextRequest } from 'next/server';
   
   export function middleware(request: NextRequest) {
     const token = request.cookies.get('session')?.value;
     if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
       return NextResponse.redirect(new URL('/login', request.url));
     }
     const response = NextResponse.next();
     response.headers.set('x-request-id', crypto.randomUUID());
     return response;
   }
   
   export const config = {
     matcher: ['/dashboard/:path*', '/api/:path*'],
   };

2. Always scope with config.matcher — never run middleware on every request.
3. Edge Runtime constraints — no Node.js APIs (fs, path). Web APIs only.
4. Common patterns: auth redirects, i18n locale detection, rate limiting headers, CSP injection.

---