git:20260813.c9ab97d to git:20260816.d23736e

49 added, 47 removed. Audit A to A.

---

name: nextjs-app-router-expert

description: "Expert guide for Next.js 15 App Router: RSC, Server Actions, Middleware, Parallel/Intercepting Routes, Streaming, and Caching strategies / Panduan ahli untuk Next.js 15 App Router."

- author: vibes-plug-swarm

+ author: "vibes-plug-swarm"

---

# Next.js 15 App Router Expert

[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)

---

## English

### Description

- An advanced guide dedicated exclusively to the Next.js 15 App Router ecosystem. Moves beyond basic frontend development to cover deep architectural patterns like React Server Components (RSC), advanced Server Actions, Middleware routing, Parallel & Intercepting Routes, Streaming/Suspense, Partial Prerendering (PPR), and complex cache invalidation.

+ Execute advanced Next.js 15 App Router architectural patterns: React Server Components (RSC), React 19 Server Actions, Middleware routing, Parallel/Intercepting Routes, Streaming/Suspense, Partial Prerendering (PPR), and explicit cache invalidation.

### Trigger Conditions

- - When architecting a new Next.js 15 application using the `app/` directory.

- - When migrating an older `pages/` directory Next.js app to App Router.

- - When implementing complex UI patterns like modals with Intercepting Routes (`(.)route`).

- - When debugging caching issues (stale data, Next.js cache tags, `revalidatePath`).

- - When building dashboards that require Partial Prerendering (PPR) or streaming.

+ - Architecting new Next.js 15 `app/` directory applications.

+ - Migrating `pages/` directory to App Router.

+ - Implementing complex UI patterns (modals via Intercepting Routes).

+ - Debugging caching (`force-cache`, `revalidatePath`, tags).

+ - Building interfaces requiring Partial Prerendering (PPR) or Streaming.

### Core Architectural Patterns

#### 1. React Server Components (RSC) vs Client Components

- - **Default to Server**: Every component in `app/` is a Server Component by default. They cannot use hooks (`useState`, `useEffect`) or browser APIs.

- - **Client Boundaries**: Only add `"use client"` when interactivity (events, state) or browser APIs (window) are needed. Push client boundaries as far down the component tree as possible.

- - **Interleaving**: You *can* pass a Server Component as a `children` prop to a Client Component, but you cannot directly import a Server Component into a Client Component.

+ - **Default to Server**: All `app/` components are Server Components. No hooks (`useState`) or browser APIs.

+ - **Client Boundaries**: Add `"use client"` only for interactivity/browser APIs. Push client boundaries down the component tree.

+ - **Interleaving**: Pass Server Components as `children` to Client Components; do not import Server Components into Client Components directly.

- #### 2. Advanced Server Actions

- Use Server Actions for all mutations instead of creating separate API routes.

+ #### 2. React 19 Server Actions

+ Use Server Actions (`useActionState`) for all mutations. Avoid separate API routes.

```typescript

'use server'

import { revalidateTag } from 'next/cache';

import { z } from 'zod';

import { db } from '@/lib/db';

const schema = z.object({ email: z.string().email() });

export async function subscribeUser(prevState: any, formData: FormData) {

const parsed = schema.safeParse({ email: formData.get('email') });

- if (!parsed.success) {

- return { error: 'Invalid email' };

- }

+ if (!parsed.success) return { error: 'Invalid email' };

await db.subscribers.insert({ email: parsed.data.email });

- revalidateTag('subscribers'); // Target specific cache invalidation

+ revalidateTag('subscribers');

return { success: true };

}

```

#### 3. Parallel & Intercepting Routes (Modals)

- Use this pattern to render a modal while preserving the background page and keeping the modal shareable via URL.

- - **Intercepting (`(.)[segment]`)**: Matches the route on client-side navigation.

- - **Parallel (`@modal`)**: Renders simultaneously with the `layout.tsx` children.

+ Render modals preserving background page context and URL shareability.

+ - **Intercepting (`(.)[segment]`)**: Matches route on client-side navigation.

+ - **Parallel (`@modal`)**: Renders simultaneously with `layout.tsx` children.

- Directory structure for a photo modal:

```

app/

├── @modal/

- │ ├── (.)photos/[id]/page.tsx (Intercepted modal)

+ │ ├── (.)photos/[id]/page.tsx

│ └── default.tsx

├── photos/

- │ └── [id]/page.tsx (Direct full-page access)

+ │ └── [id]/page.tsx

├── layout.tsx

└── page.tsx

```

#### 4. Caching & Data Fetching (Next.js 15)

- In Next.js 15, fetch requests are **not cached by default**. You must explicitly opt-in:

+ Fetch requests are **not cached by default**. Opt-in explicitly:

```typescript

- // Cache indefinitely

+ // Indefinite cache

const res = await fetch('https://api.example.com/data', { cache: 'force-cache' });

- // Cache with Time-Based Revalidation (ISR)

+ // Time-Based Revalidation (ISR)

const res = await fetch('https://api.example.com/data', { next: { revalidate: 3600 } });

- // On-Demand Revalidation via Tags

+ // On-Demand Revalidation

const res = await fetch('https://api.example.com/data', { next: { tags: ['collection'] } });

- // In your server action: revalidateTag('collection')

+ // In server action: revalidateTag('collection')

```

#### 5. Streaming & Partial Prerendering (PPR)

- Wrap slow data fetches in `<Suspense>` to stream UI instantly to the user:

+ Wrap slow fetches in `<Suspense>` to stream UI instantly:

```tsx

import { Suspense } from 'react';

import { Skeleton } from '@/components/ui/skeleton';

export default function DashboardPage() {

return (

<main>

<h1>Dashboard</h1>

</Suspense>

</main>

);

}

```

## Orchestration & Integration

- - Enhances `senior-frontend` with deep Next.js App Router architectural knowledge.

- - Integrates with `tanstack-query-expert` for client-side hydration patterns in RSC.

- - Works with `spa-orchestrator` when deciding between SPA and SSR architectures.

+ - **`senior-frontend`**: Enhances UI/UX with Next.js App Router RSC and Next 15 caching.

+ - **`js-backend-expert`**: Bridges frontend Server Actions with backend Node.js/Bun architectures.

+ - **`tanstack-query-expert`**: Manages client-side state hydration from RSC.

+ - **`performance-web-vitals`**: Optimizes Core Web Vitals using Streaming and PPR.

---

## Bahasa Indonesia

### Deskripsi

- Panduan lanjutan yang didedikasikan khusus untuk ekosistem Next.js 15 App Router. Mencakup pola arsitektur mendalam seperti React Server Components (RSC), Server Actions lanjutan, Middleware, Parallel & Intercepting Routes, Streaming, Partial Prerendering (PPR), dan strategi invalidasi cache.

+ Terapkan pola arsitektur lanjutan Next.js 15 App Router: React Server Components (RSC), React 19 Server Actions, Middleware, Parallel/Intercepting Routes, Streaming/Suspense, Partial Prerendering (PPR), dan invalidasi cache eksplisit.

### Kondisi Pemicu

- - Saat merancang aplikasi Next.js 15 baru menggunakan direktori `app/`.

- - Saat memigrasikan aplikasi Next.js lama dari direktori `pages/`.

- - Saat mengimplementasikan pola UI kompleks seperti modal dengan Intercepting Routes.

- - Saat melakukan debugging masalah caching (data usang, `revalidatePath`, tags).

- - Saat membangun dashboard yang membutuhkan streaming atau Partial Prerendering (PPR).

+ - Merancang aplikasi Next.js 15 `app/` direktori baru.

+ - Migrasi direktori `pages/` ke App Router.

+ - Implementasi pola UI kompleks (modal via Intercepting Routes).

+ - Debugging cache (`force-cache`, `revalidatePath`, tags).

+ - Membangun antarmuka dengan Partial Prerendering (PPR) atau Streaming.

### Pola Arsitektur Inti

#### 1. RSC vs Client Components

- Secara default, semua komponen adalah Server Components. Tambahkan `"use client"` hanya pada node paling bawah di pohon komponen yang membutuhkan interaktivitas atau API browser. Anda bisa meneruskan Server Component sebagai `children` ke Client Component.

+ - **Default Server**: Semua komponen `app/` adalah Server Components. Tanpa hooks/API browser.

+ - **Batas Klien**: Tambahkan `"use client"` hanya untuk interaktivitas. Dorong batas klien ke bawah struktur komponen.

+ - **Interleaving**: Berikan Server Components sebagai `children` ke Client Components; jangan impor langsung.

- #### 2. Server Actions Lanjutan

- Gunakan Server Actions bersama dengan `useActionState` (React 19) untuk form dan mutasi data, menggantikan API routes konvensional. Pastikan selalu memvalidasi input di server dengan Zod dan menggunakan `revalidatePath` atau `revalidateTag` untuk memperbarui UI.

+ #### 2. React 19 Server Actions

+ Gunakan Server Actions (`useActionState`) untuk mutasi. Hindari pembuatan API routes terpisah.

+ Validasi input di server dengan Zod dan gunakan `revalidateTag` untuk perbarui UI.

#### 3. Parallel & Intercepting Routes

- Sangat berguna untuk modal (misal: modal login, modal foto). Rute dicegat saat navigasi client-side sehingga URL berubah dan modal terbuka di atas halaman saat ini. Jika URL diakses langsung (refresh), halaman penuh yang dirender.

+ Gunakan untuk modal. Mencegat rute navigasi client-side (URL berubah, modal di atas halaman saat ini). Refresh langsung memuat halaman penuh.

#### 4. Caching di Next.js 15

- Di Next.js 15, `fetch` **tidak di-cache secara default**. Anda harus secara eksplisit mengaktifkan cache menggunakan `{ cache: 'force-cache' }` atau `{ next: { revalidate: 3600 } }`. Gunakan cache tags untuk memicu pembaruan on-demand pada data tertentu.

+ Fungsi `fetch` **tidak di-cache default**. Aktifkan eksplisit via `{ cache: 'force-cache' }` atau `{ next: { revalidate: 3600 } }`. Gunakan cache tags untuk invalidasi spesifik.

- #### 5. Streaming dengan Suspense

- Gunakan batas `<Suspense>` untuk membungkus komponen Server yang melakukan pengambilan data lambat. Ini memungkinkan bagian halaman yang statis dimuat seketika, sementara bagian yang dinamis mengalir (*stream*) ke klien setelah data siap.

+ #### 5. Streaming & Partial Prerendering (PPR)

+ Bungkus pengambilan data lambat dengan `<Suspense>` untuk menampilkan UI awal seketika sambil menunggu data (streaming).

## Integrasi Orkestrasi

- - Memperkuat `senior-frontend` dengan pengetahuan arsitektur mendalam Next.js.

- - Terintegrasi dengan `tanstack-query-expert` untuk pola hidrasi state dari RSC ke sisi klien.

- - Bekerja bersama `spa-orchestrator` saat menentukan keputusan arsitektur antara SPA dan SSR.

+ - **`senior-frontend`**: Menguatkan UI/UX dengan pemahaman arsitektur RSC dan cache Next 15.

+ - **`js-backend-expert`**: Menghubungkan Server Actions dengan arsitektur backend Node.js/Bun.

+ - **`tanstack-query-expert`**: Mengelola hidrasi state client-side dari RSC.

+ - **`performance-web-vitals`**: Optimalisasi Core Web Vitals menggunakan Streaming dan PPR.