Cara Upgrade Next.js 15 ke Next.js 16

Upgrade dari Next.js 15 ke Next.js 16 paling cepat dilakukan lewat codemod resmi npx @next/codemod@canary upgrade latest, yang otomatis memperbarui konfigurasi Turbopack, mengganti middleware jadi proxy, dan menghapus prefix unstable_ yang sudah stabil. Setelah itu, langkah manual yang wajib dicek: breaking change Turbopack sebagai bundler default dan akses asinkron penuh untuk params/searchParams/cookies()/headers().

Ringkasan cepat:

1. Cara tercepat upgrade: jalankan codemod resmi npx @next/codemod@canary upgrade latest, yang otomatis membenahi konfigurasi Turbopack, migrasi middleware ke proxy, dan menghapus prefix unstable_ yang sudah stabil.
2. Turbopack jadi bundler default untuk next dev maupun next build, bukan lagi opt-in lewat flag — proyek dengan webpack() kustom di next.config perlu dimigrasikan atau memakai flag --webpack.
3. Akses params, searchParams, cookies(), headers(), dan draftMode() wajib lewat await; mode kompatibilitas sinkron dari Next.js 15 sudah dihapus total.
4. Flag eksperimental dynamicIO/ppr digantikan opsi stabil cacheComponents, dan revalidateTag sekarang butuh argumen kedua berupa profil cacheLife.
5. Setelah semua langkah dijalankan, npm run build wajib dipakai untuk menangkap breaking change yang tidak selalu tertangkap codemod, seperti konfigurasi webpack kustom atau parallel routes tanpa default.js.

Apa yang Berubah Besar di Next.js 16?#

Tiga perubahan paling berdampak untuk kebanyakan proyek App Router: Turbopack jadi bundler default untuk next dev maupun next build (bukan lagi opt-in lewat flag), dukungan akses sinkron sementara untuk params/searchParams/ cookies()/headers() yang diperkenalkan di Next.js 15 sudah dihapus total, dan flag eksperimental dynamicIO/ppr digantikan opsi stabil cacheComponents. Menurut dokumentasi resmi upgrade Next.js 16, proyek juga perlu Node.js minimal 20.9 dan TypeScript minimal 5.1. Opsi cacheComponents ini yang membuat Partial Prerendering (PPR) jadi stabil — static shell sebuah route diprerender saat build, lalu bagian dinamis di-stream belakangan lewat batas <Suspense>.

Situs ini sendiri (irfanramadhan.com) masih berjalan di Next.js 15.5 saat artikel ini ditulis, jadi langkah-langkah di bawah adalah urutan yang sama yang akan dijalankan saat proyek ini nanti dimigrasikan.

Ringkasan Perubahan yang Perlu Dicek#

• Turbopack default untuk dev dan build, proyek dengan konfigurasi webpack kustom di next.config akan gagal build kecuali dimigrasikan atau memakai flag --webpack.
• Opsi turbopack pindah dari experimental.turbopack ke level atas next.config.
• params, searchParams, cookies(), headers(), draftMode() wajib diakses dengan await, tidak ada lagi mode kompatibilitas sinkron.
• experimental.dynamicIO dan experimental.ppr dihapus, digantikan opsi stabil cacheComponents: true.
• revalidateTag sekarang butuh argumen kedua berupa profil cacheLife (mis. revalidateTag('posts', 'max')), bukan lagi argumen tunggal.
• File middleware.ts diganti nama jadi proxy.ts dengan fungsi bernama proxy (runtime edge tidak didukung di proxy, hanya nodejs).
• Fitur lama dihapus total: dukungan AMP, perintah next lint, serverRuntimeConfig/publicRuntimeConfig, dan beberapa opsi devIndicators.

Dokumentasi resmi menjelaskan perubahan revalidateTag ini secara eksplisit, termasuk konsekuensinya kalau argumen kedua tidak ditambahkan:

revalidateTag now requires a second argument specifying a cacheLife profile. The single-argument form is deprecated and will produce a TypeScript error.

— Dokumentasi resmi Next.js, panduan upgrade versi 16

Diringkas dalam tabel, tujuh perubahan di atas beserta tindakan yang perlu dilakukan:

Bagaimana Cara Upgrade ke Next.js 16 Langkah demi Langkah?#

Urutan berikut mengikuti panduan resmi Next.js, dari cara tercepat (codemod otomatis) sampai verifikasi manual untuk breaking change yang tidak selalu tertangkap otomatis.

1. Jalankan Codemod Upgrade Resmi#

npx @next/codemod@canary upgrade latest

Codemod ini memperbarui next.config untuk memakai konfigurasi turbopack baru, memigrasikan konvensi middleware yang sudah deprecated ke proxy, menghapus prefix unstable_ dari API yang sudah stabil (mis. cacheLife, cacheTag), dan menghapus Route Segment Config experimental_ppr yang sudah tidak berlaku.

Kalau proyek masih memakai akses sinkron ke params, searchParams, cookies(), headers(), atau draftMode() dari masa kompatibilitas Next.js 15, jalankan juga codemod terpisah untuk API asinkron:

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

2. Atau Instal Paket Secara Manual#

Kalau lebih suka kontrol manual daripada codemod otomatis:

npm install next@latest react@latest react-dom@latest

Kalau proyek memakai TypeScript, perbarui juga @types/react dan @types/react-dom ke versi terbaru supaya tipe params/searchParams (sekarang berbasis Promise) tidak menimbulkan error tipe yang membingungkan.

3. Sesuaikan Skrip Turbopack di package.json#

Karena Turbopack sudah jadi default, flag --turbopack yang sebelumnya ditulis manual di skrip dev/build tidak lagi diperlukan:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Kalau proyek masih punya konfigurasi webpack kustom di next.config dan belum sempat dimigrasikan ke opsi Turbopack yang setara, next build akan gagal secara sengaja untuk mencegah salah konfigurasi. Tiga opsi yang tersedia: migrasikan konfigurasi webpack ke opsi Turbopack, jalankan next build --turbopack untuk mengabaikan config webpack lama, atau tetap pakai next build --webpack untuk opt-out dari Turbopack sepenuhnya.

If your project has a custom webpack configuration and you run next build (which now uses Turbopack by default), the build will fail to prevent misconfiguration issues.

— Dokumentasi resmi Next.js, panduan upgrade versi 16

4. Perbaiki Akses Sinkron ke Params dan SearchParams#

Ini penyebab error paling umum setelah upgrade. Semua akses ke params, searchParams, cookies(), dan headers() sekarang wajib lewat await:

// Sebelum (Next.js 15, mode kompatibilitas sinkron - sudah tidak berlaku)
export default function Page({ params }: { params: { slug: string } }) {
  return <h1>{params.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>;
}

Untuk mempermudah migrasi tipe, jalankan npx next typegen agar Next.js menghasilkan helper tipe global (PageProps, LayoutProps, RouteContext) yang sudah otomatis membungkus params/searchParams sebagai Promise.

5. Verifikasi Build dan Jalankan Aplikasi#

Setelah semua langkah di atas, jalankan build produksi untuk memastikan tidak ada breaking change yang terlewat:

npm run build
npm run start

Perhatikan log build untuk peringatan terkait konfigurasi images (domains yang deprecated jadi remotePatterns, minimumCacheTTL default berubah dari 60 detik jadi 4 jam) dan parallel routes yang sekarang wajib punya file default.js eksplisit di setiap slot, kalau tidak build akan gagal.

Kalau build masih gagal setelah codemod (mis. error webpack config found, akses params/searchParams sinkron, atau parallel routes tanpa default.js), artikel cara memperbaiki error upgrade Next.js 16 membahas keempat error paling sering muncul beserta perbaikannya satu per satu.

Kenapa Turbopack Jadi Default Berdampak Besar?#

Turbopack menjadi bundler default untuk next dev maupun next build mulai Next.js 16, bukan lagi eksperimen di balik flag --turbopack. Dampak praktisnya: proyek yang mengandalkan webpack() kustom di next.config untuk hal seperti loader tambahan atau alias resolusi modul perlu memigrasikan konfigurasi itu ke opsi turbopack yang setara sebelum build produksi berhasil tanpa flag --webpack.

Rincian klaim performa (build 2-5x lebih cepat, Fast Refresh hingga 10x) dan cara opt-out lewat flag --webpack dibahas lebih dalam di artikel khusus Turbopack jadi default di Next.js 16.

Perubahan ini melanjutkan arah yang sudah dibahas di artikel React Compiler Next.js sebelumnya. Next.js 16 juga menstabilkan dukungan React Compiler bawaan (opsi reactCompiler naik dari status eksperimental), sehingga proyek yang sudah memakainya di Next.js 15 tinggal melanjutkan tanpa perubahan tambahan.

Ringkasan: Codemod Resmi, Breaking Change Wajib Cek, dan Verifikasi Build#

• Cara tercepat upgrade adalah codemod resmi npx @next/codemod@canary upgrade latest, yang menangani sebagian besar perubahan mekanis (konfigurasi Turbopack, migrasi middleware ke proxy, penghapusan prefix unstable_) secara otomatis.
• Dua breaking change yang paling sering bikin build gagal: konfigurasi webpack kustom yang belum dimigrasikan ke Turbopack, dan akses sinkron ke params/searchParams/cookies()/headers() yang sekarang wajib await.
• Kalau proyek masih memakai revalidateTag dengan argumen tunggal, itu juga perlu diperbarui. Perbandingan lengkap opsi caching Next.js App Router sudah dibahas di artikel revalidatePath vs revalidateTag.
• Selalu jalankan npm run build setelah migrasi untuk menangkap breaking change yang tidak selalu terlihat lewat codemod saja. Kalau butuh bantuan audit atau migrasi proyek Next.js, lihat layanan web development yang ditawarkan.
• Setelah migrasi selesai, dev server Next.js 16 membuka endpoint /_next/mcp yang bisa disambungkan ke AI coding assistant lewat Next.js Devtools MCP — fitur ini tidak tersedia di Next.js 15.