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().

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.

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.

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.

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.

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.

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#

• 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.