Lewati ke konten
Tutorial

Memperbaiki Error Upgrade Next.js 16

M. Irfan Ramadhan4 menit baca
Layar komputer menampilkan kode dan output terminal berwarna gelap.
Foto: Unsplash
Daftar Isi

Error paling umum setelah upgrade ke Next.js 16 mencakup build gagal karena konfigurasi webpack terdeteksi Turbopack, akses sinkron ke params/searchParams/cookies()/headers() yang kini benar-benar dilarang (bukan sekadar warning), parallel routes tanpa default.js, dan revalidateTag() dengan satu argumen yang jadi error TypeScript.

Ringkasan cepat:

  1. Next.js 16 mengubah warning masa transisi Next.js 15 jadi error keras: konfigurasi webpack yang terdeteksi Turbopack, akses sinkron ke params/searchParams/cookies()/headers(), parallel routes tanpa default.js, dan revalidateTag() dengan satu argumen.
  2. Jalankan npx @next/codemod@canary upgrade latest lebih dulu sebelum debugging manual — migrasi mekanis (konfigurasi Turbopack, rename middleware ke proxy, penghapusan prefix unstable_) sudah otomatis tertangani.
  3. Error "webpack config found" diperbaiki dengan memindahkan opsi ke properti turbopack top-level, atau tetap pakai next build --webpack kalau belum siap migrasi penuh.
  4. Akses params/searchParams/cookies()/headers() wajib pakai await — jalankan codemod next-async-request-api untuk migrasi otomatis, lalu npx next typegen untuk regenerasi tipe bantuan.
  5. Parallel routes (folder berawalan @) wajib punya default.js, dan revalidateTag() sekarang butuh argumen kedua berupa profil cacheLife (atau pakai updateTag() di Server Action untuk efek read-your-writes).

Kenapa Next.js 16 Sering Error Setelah Upgrade?

Next.js 15 memperkenalkan banyak perubahan sebagai peringatan (warning) dengan periode transisi sinkron-asinkron yang masih dibolehkan sementara. Menurut panduan resmi upgrade ke versi 16, periode transisi itu berakhir total di versi 16: kode yang di Next.js 15 cuma menampilkan warning di console sekarang benar-benar gagal build atau error di runtime. Turbopack juga berubah dari opsional (--turbopack) menjadi default penuh untuk next dev maupun next build.

Cara Cepat Melihat Semua Error Sekaligus

Jalankan npx @next/codemod@canary upgrade latest dulu sebelum debugging manual — codemod ini otomatis menangani migrasi konfigurasi Turbopack, migrasi middleware ke proxy, dan penghapusan prefix unstable_. Baru setelah itu jalankan npm run build untuk melihat error yang tersisa satu per satu.

Error Apa Saja yang Paling Sering Muncul Setelah Upgrade Next.js 16?

Error/PeringatanPenyebabPerbaikan Singkat
Build gagal, disebut konfigurasi webpack ditemukannext.config.ts punya opsi webpack (manual atau dari plugin pihak ketiga), sedangkan next build kini memakai Turbopack secara defaultMigrasi ke opsi turbopack, atau jalankan next build --webpack
Akses params/searchParams/cookies()/headers() sinkron gagal totalPeriode transisi sinkron Next.js 15 sudah berakhir di versi 16Bungkus dengan await, jalankan codemod next-async-request-api
Build gagal di parallel routesSlot parallel routes (mis. @modal) tidak punya default.jsTambahkan default.js yang memanggil notFound() atau return null
revalidateTag() error TypeScriptrevalidateTag() sekarang wajib argumen kedua berupa profil cacheLifeUbah revalidateTag('tag') jadi revalidateTag('tag', 'max'), atau pakai updateTag()
Error terkait experimental.dynamicIO/experimental.useCacheKedua flag eksperimental ini sudah dihapus total di versi 16Ganti ke opsi top-level cacheComponents: true, atau hapus kalau memang tidak dipakai

Bagaimana Cara Memperbaiki Error "Webpack Config Found" Saat Build?

Turbopack sekarang jadi bundler default untuk next build, jadi kalau next.config.ts masih punya opsi webpack kustom, build akan gagal untuk mencegah konfigurasi yang salah terpakai secara diam-diam. Ada tiga jalan keluar sesuai dokumentasi resmi:

# 1. Tetap pakai Turbopack, abaikan konfigurasi webpack
next build --turbopack
 
# 2. Tetap pakai webpack sepenuhnya
next build --webpack

Kalau memilih migrasi penuh ke Turbopack, pindahkan opsi ke properti turbopack top-level di next.config.ts (bukan lagi di dalam experimental.turbopack seperti Next.js 15). Kalau errornya muncul padahal project sendiri tidak pernah menulis opsi webpack, cek dependency pihak ketiga (Sentry, plugin PWA, dll.) yang kemungkinan menambahkannya otomatis ke config. Migrasi ini bukan cuma soal menghilangkan error — lihat dampak Turbopack jadi default di Next.js 16 untuk angka build 2-5x lebih cepat dan Fast Refresh hingga 10x yang jadi alasan Next.js mendorong migrasi ini.

Bagaimana Cara Memperbaiki Error Akses Params dan SearchParams Sinkron?

Di Next.js 16, params, searchParams, cookies(), headers(), dan draftMode() hanya bisa diakses secara asinkron — akses sinkron yang di Next.js 15 masih sekadar warning sekarang benar-benar tidak berfungsi.

Starting with Next.js 16, synchronous access is fully removed. These APIs can only be accessed asynchronously.

— Next.js 16 Upgrade Guide, bagian Async Request APIs

Jalankan codemod resmi untuk migrasi otomatis ke sebagian besar file:

npx @next/codemod@canary next-async-request-api .

Untuk kasus yang tidak tertangkap codemod, ubah manual dengan await:

// Sebelum (Next.js 15, sinkron)
export default function Page({ params }: { params: { slug: string } }) {
  const { slug } = params;
  return <h1>{slug}</h1>;
}
 
// Sesudah (Next.js 16, wajib async)
export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  return <h1>{slug}</h1>;
}

Jalankan npx next typegen setelah migrasi untuk menghasilkan ulang tipe bantuan PageProps/LayoutProps/RouteContext secara otomatis, supaya IDE langsung mendeteksi kalau ada akses sinkron yang terlewat.

Kenapa Build Gagal Karena Parallel Routes Tanpa default.js?

Semua slot parallel routes (folder dengan awalan @, misalnya @modal atau @sidebar) sekarang wajib punya file default.js — tanpa itu, build langsung gagal. Sebelumnya Next.js diam-diam mengizinkan slot kosong tanpa fallback eksplisit.

All parallel route slots now require explicit default.js files. Builds will fail without them.

— Next.js 16 Upgrade Guide, bagian Parallel Routes default.js requirement

// app/@modal/default.tsx
import { notFound } from "next/navigation";
 
export default function Default() {
  notFound();
}

Atau cukup return null kalau slot tersebut memang boleh kosong tanpa memicu halaman 404.

Bagaimana Cara Memperbaiki Error revalidateTag Setelah Upgrade?

revalidateTag() dengan satu argumen sekarang menghasilkan error TypeScript karena wajib argumen kedua berupa profil cacheLife:

// Sebelum — error TypeScript di Next.js 16
revalidateTag("posts");
 
// Sesudah — wajib sertakan profil cacheLife
revalidateTag("posts", "max");

Kalau butuh efek "read-your-writes" (perubahan langsung terlihat di request yang sama, bukan stale-while-revalidate), pakai updateTag() di dalam Server Action sebagai gantinya — fungsi baru yang memang dirancang untuk kasus itu, berbeda dari pola caching yang sudah dibahas di artikel Cache Components Next.js 16.

Ringkasan: Codemod Dulu, Baru Perbaiki Empat Error Manual

  • Jalankan npx @next/codemod@canary upgrade latest lebih dulu sebelum debugging manual — sebagian besar migrasi mekanis (konfigurasi Turbopack, rename middleware ke proxy, penghapusan prefix unstable_) sudah otomatis.
  • Error paling sering: konfigurasi webpack yang terdeteksi Turbopack, akses sinkron ke params/searchParams/cookies()/headers() yang kini benar-benar dilarang, parallel routes tanpa default.js, dan revalidateTag() tanpa argumen kedua.
  • Kalau upgrade-nya sendiri belum dijalankan, baca dulu langkah lengkapnya di cara upgrade Next.js 15 ke Next.js 16 sebelum masuk ke troubleshooting di artikel ini.
  • Butuh bantuan mengaudit atau memperbaiki error upgrade Next.js di proyek sendiri? Lihat layanan web development yang ditawarkan.

nextjs 16 · troubleshooting · turbopack · breaking changes · upgrade

Pertanyaan yang Sering Diajukan

Kenapa build Next.js 16 gagal padahal tidak ada custom konfigurasi webpack?

Kemungkinan besar ada plugin pihak ketiga (mis. Sentry, PWA, atau analytics) yang menambahkan opsi `webpack` ke `next.config.ts` secara otomatis. Karena Turbopack kini jadi bundler default untuk `next build`, opsi itu tetap terdeteksi dan menggagalkan build meski developer tidak menulisnya sendiri. Solusinya: pindahkan opsi ke properti `turbopack` top-level, atau jalankan `next build --webpack` sementara sambil menelusuri dependency mana yang menambahkannya.

Apakah semua project wajib pindah ke Turbopack saat upgrade ke Next.js 16?

Tidak wajib. Kalau masih butuh webpack (misalnya karena loader kustom yang belum kompatibel), tambahkan flag `--webpack` di skrip `build`/`dev` untuk tetap memakai webpack sambil menunda migrasi penuh ke Turbopack. Tapi migrasi tetap layak dipertimbangkan lebih awal — Turbopack yang jadi default penuh di Next.js 16 diklaim mempercepat build 2-5x dan Fast Refresh hingga 10x dibanding webpack.

Apakah codemod resmi Next.js bisa memperbaiki semua error upgrade otomatis?

Tidak sepenuhnya. Codemod `@next/codemod upgrade` menangani migrasi mekanis seperti konfigurasi Turbopack, penghapusan prefix `unstable_`, dan rename `middleware` ke `proxy`, tapi perubahan seperti akses `params`/`searchParams` async atau penambahan `default.js` di parallel routes tetap perlu dicek manual di beberapa kasus. Setelah menjalankan codemod, jalankan `npm run build` untuk melihat error yang tersisa satu per satu sebelum build benar-benar hijau.

Artikel Terkait

M. Irfan Ramadhan

SEO Specialist & Web Developer

Menulis tentang SEO teknis, GEO/AI search, dan pengembangan web modern berdasarkan pengalaman langsung mengerjakan proyek klien.