📚 Next.js App Router: Lapisan Caching & Sumber Bug "Data Basi"

Versi referensi: Next.js 16 (rilis Oktober 2025, blog resmi nextjs.org/blog/next-16). Perubahan besar vs 14/15 — materi ini menyebut dua model: legacy model (tanpa cacheComponents) dan Cache Components (model baru).

🎯 Tujuan Belajar

Besok bisa: - Menjelaskan 4 lapisan cache Next.js App Router dan mana yang menyebabkan "data basi" di kasus tertentu - Debug laporan "sudah revalidate tapi UI masih lama" dengan checklist per lapisan - Memakai model baru Next.js 16: use cache, cacheLife, cacheTag, updateTag, refresh - Memilih API invalidasi yang benar untuk Server Action vs webhook

🏗️ Empat Lapisan Caching (diagnosis bug "data basi")

Aturan praktis: keluhan "lihat di halaman A sudah update, halaman B masih lama" atau "refresh dua kali baru berubah" → lapisan 4 (Client Router Cache) atau kombinasi. Keluhan "bahya request langsung ke server masih lama" → lapisan 2/3.

Versi 15+ legacy: fetch tidak di-cache default (opt-in via cache: 'force-cache' / next.revalidate / next.tags). Client Router Cache punya staleTimes default: static 5 menit, dynamic 0 detik (eksperimental). Cache entry di Client Router Cache yang di-prefetch bisa basi sampai 5 menit walau server sudah revalidate — kasus GitHub discussion #86538 (Nov 2025) persis ini, fix: turunkan experimental.staleTimes.static.

💻 Kode Nyata — Model Baru Next.js 16

Enable:

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  cacheComponents: true, // 'use cache' dkk. aktif; PPR jadi bagian dari ini
}
export default nextConfig

Cached data function + tag + lifetime:

// lib/posts.ts — Next.js 16, cacheComponents: true
import { cacheLife, cacheTag } from 'next/cache'

export async function getPost(slug: string) {
  'use cache'
  cacheLife('days')          // stale 5m, revalidate 1d, expire 1w
  cacheTag(`post-${slug}`, 'posts')

  return db.post.findUnique({ where: { slug } })
}

Preset cacheLife (docs resmi, di-update Sep 2026):

Tiga angka ini beda maknanya: - stale → boleh serve tanpa cek server (client router pakai x-nextjs-stale-time header; minimum 30 detik di-enforce) - revalidate → lewat waktu itu, serve cache + refresh di background (SWR, seperti ISR) - expire → lewat waktu itu, request blocking sampai fresh

Invalidasi — pilih sesuai konteks:

// 1) Server Action, user HARUS langsung lihat hasilnya (read-your-writes)
'use server'
import { updateTag } from 'next/cache'
export async function createPost(formData: FormData) {
  const post = await db.post.create({ data: { title: formData.get('title') } })
  updateTag('posts')             // hanya boleh dari Server Action; request
  updateTag(`post-${post.id}`)   // berikutnya BLOCKING sampai fresh
}

// 2) Route Handler / webhook CMS — stale-while-revalidate
// app/api/revalidate/route.ts
import { revalidateTag } from 'next/cache'
export async function POST(req: Request) {
  if (req.headers.get('x-secret') !== process.env.REVAL_SECRET) {
    return Response.json({ ok: false }, { status: 401 })
  }
  const { id } = await req.json()
  revalidateTag(id, 'max')       // Next 16: argumen ke-2 WAJIB
  return Response.json({ revalidated: true })
}

// 3) refresh() — Server Action, hanya refresh data TIDAK di-cache
import { refresh } from 'next/cache'
refresh() // notification count, live metrics — cache shell tak tersentuh

Catatan penting Next 16: - revalidateTag(tag) satu argumen → deprecated. Tanpa argumen kedua behave seperti { expire: 0 }. Pakai revalidateTag(tag, 'max') untuk SWR. - updateTag hanya valid di Server Action — dipanggil di Route Handler → throw. Di webhook pakai revalidateTag(tag, { expire: 0 }) kalau butuh expire instan. - Dengan cacheComponents: true, export dynamic, revalidate, fetchCache di route segment → build gagal. Semua caching pindah ke use cache. - Cache key use cache = build ID + hash fungsi + argumen seriable. Cache tidak lintas deploy (berbeda dengan fetch Data Cache & unstable_cache yang persisten). - use cache default = in-memory di server. Di serverless (instance ephemeral), entry praktis tak reuse antar-request → pertimbangkan 'use cache: remote' (cache handler Redis/KV, ada biaya network/platform). - Runtime API (cookies(), headers(), searchParams) dilarang di dalam use cache — baca di luar, pass sebagai argumen. Pelanggaran langsung: error next-request-in-use-cache; variasi tak langsung (Promise runtime lewat props/closure/Map bersama) → build hang 50 detik dengan error "Filling a cache during prerender timed out". - Versi 16.4+: ensureStatic = 'navigation' untuk memvalidasi route benar-benar statis (pengganti aman dynamic = 'force-static').

Legacy (tanpa cacheComponents) masih didukung — docs-nya kini dipisah jadi "Caching and Revalidating (Previous Model)". Di model itu: fetch(url, { next: { tags, revalidate } }), export const revalidate = 60, revalidatePath.

📊 Angka & Benchmark

• Client Router Cache default legacy: staleTimes.static = 300 s, dynamic = 0 s (docs staleTimes, nextjs.org)
• Cache Components: default profile = stale 5 m / revalidate 15 m / expire never; minimum stale client 30 s (docs cacheLife, terakhir di-update 29 Sep 2026)
• Timeout prerender use cache: 50 detik (docs troubleshooting)
• Next.js 16 (blog resmi, Okt 2025): Turbopack stable — klaim build 2–5× lebih cepat, Fast Refresh hingga 10×; >50% dev session di Next 15.3+ sudah pakai Turbopack saat rilis
• Tag cache maksimal 256 karakter (docs revalidateTag)
• DIINFERENSI dari kasus GitHub #86538: sinkronisasi penuh setelah revalidate bisa molor ~15 menit kalau staleTimes.static 300 s + SWR stack — angka kasus spesifik, bukan universal.

⚖️ Trade-off

🏭 Use Case Produksi & Failure Mode

1. Webhook CMS publish → data tetap lama di UI selama menit. Penyebab: webhook cuma revalidateTag (lapisan 2/3), Client Router Cache di browser user belum expire. Fix: invalidasi dari Server Action pakai updateTag, atau terima SWR delay.
2. revalidateTag di middleware/proxy → tidak jalan (server context salah). Pindah ke Route Handler atau Server Action.
3. Build hang 50 s di use cache → Promise runtime (cookies/searchParams) bocor masuk scope cached via props/closure/Map. Refactor: baca di luar, pass nilai primitif.
4. Serverless + use cache → hit rate nyaris nol, DB kena trafik penuh. Fix: 'use cache: remote' atau custom cache handler.
5. User A update, user A sendiri masih lihat lama → pakai updateTag, bukan revalidateTag(tag, 'max') (SWR sengaja serve stale).
6. Data beda antar halaman setelah revalidate (kasus nyata discussion #86538, Next 15.5) → kombinasi fetch cache fresh + Client Router Cache stale. Turunkan staleTimes atau trigger revalidasi via Server Action.

🛠️ Latihan Praktis

npx create-next-app@latest cache-lab --ts --app
cd cache-lab
# enable cacheComponents di next.config.ts, lalu:
NEXT_PRIVATE_DEBUG_CACHE=1 npm run dev

1. Buat komponen dengan 'use cache' + cacheLife('minutes') + cacheTag('demo'), fetch dari API publik (misal jsonplaceholder).
2. Bikin Route Handler POST /api/revalidate yang panggil revalidateTag('demo', 'max').
3. Buka dengan NEXT_PRIVATE_DEBUG_CACHE=1 — amati log cache hit/miss saat navigasi ulang.
4. Ubah API data, panggil webhook, lihat: request pertama masih stale, request kedua fresh — bukti SWR.
5. Coba baca cookies() di dalam scope use cache → amati error next-request-in-use-cache, lalu refactor jadi pass-argumen.

✅ Cek Pemahaman

1. Server log menunjukkan revalidateTag sudah jalan dan data server fresh, tapi user yang navigasi via <Link> masih melihat konten lama. Lapisan cache mana yang jadi penyebab, dan dua cara memperbaikinya?
2. Beda perilaku revalidateTag(tag, 'max') vs updateTag(tag) pada request yang datang tepat setelah pemanggilan?
3. Kenapa use cache dengan stale < 30 detik di-exclude dari prerender/App Shell?

(Jawaban: 1. Client Router Cache; fix via Server Action updateTag/refresh, atau turunkan staleTimes. 2. 'max' = serve stale + revalidate background; updateTag = blocking sampai fresh. 3. Prefetch link akan expire sebelum user sempat klik — cache entry tak berguna.)

🔑 Poin Kunci

• Bug "data basi" hampir selalu bukan satu cache — diagnose per lapisan: request memoization → server data cache → full route cache → client router cache.
• Next.js 16: caching jadi opt-in eksplisit via cacheComponents + use cache; segmen config lama (dynamic, revalidate, fetchCache) ditolak build.
• Tiga angka cacheLife: stale (client), revalidate (SWR), expire (blocking). Jangan campur maknanya.
• Pilih API invalidasi berdasarkan konteks: updateTag (Server Action, read-your-writes) / revalidateTag(tag, profile) (webhook, SWR) / refresh() (data uncached).
• use cache default in-memory & reset per deploy — serverless butuh 'use cache: remote'.

➡️ Eksplorasi Lanjutan

• use cache: private — scope cached yang boleh baca request API (compliance/dedup lintas Cache Function)
• Custom cacheHandlers — ganti LRU in-memory dengan Redis sendiri
• cacheTag + invalidasi granular per-entity (pattern webhook Contentful: tag = entry ID)
• Next.js Devtools MCP (baru di 16) — debugging cache via AI agent
• Migrasi PPR lama: docs "Migrating to Cache Components" + codemod remove-experimental_ppr

Sumber: nextjs.org/blog/next-16 (Okt 2025) · docs use cache, cacheLife, cacheTag, revalidateTag, updateTag, staleTimes, "Migrating to Cache Components", "Caching without Cache Components" (update terakhir Agt–Sep 2026) · GitHub discussion vercel/next.js #86538 & #91785.