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](https://nextjs.org/docs/app/guides/upgrading/version-16),
proyek juga perlu Node.js minimal 20.9 dan TypeScript minimal 5.1.
Opsi `cacheComponents` ini yang membuat [Partial Prerendering (PPR) jadi
stabil](/blog/partial-prerendering-ppr-nextjs-16-adalah) — 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](https://nextjs.org/docs/app/guides/upgrading/version-16)

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

| Perubahan | Tindakan yang Diperlukan |
| --- | --- |
| Turbopack default untuk dev & build | Migrasikan konfigurasi `webpack` kustom, atau pakai flag `--webpack` |
| Opsi `turbopack` pindah level | Dari `experimental.turbopack` ke level atas `next.config` |
| Akses `params`/`searchParams`/`cookies()`/`headers()` | Wajib lewat `await`, mode sinkron sudah dihapus total |
| `experimental.dynamicIO`/`experimental.ppr` dihapus | Ganti ke opsi stabil `cacheComponents: true` |
| `revalidateTag` butuh argumen kedua | Tambahkan profil `cacheLife`, mis. `revalidateTag('posts', 'max')` |
| `middleware.ts` jadi `proxy.ts` | Ganti nama file dan fungsi, `edge` runtime tidak didukung di `proxy` |
| Fitur lama dihapus total | AMP, `next lint`, `serverRuntimeConfig`/`publicRuntimeConfig`, sebagian `devIndicators` |

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

Urutan berikut mengikuti [panduan resmi Next.js](https://nextjs.org/docs/app/guides/upgrading/version-16),
dari cara tercepat (codemod otomatis) sampai verifikasi manual untuk
breaking change yang tidak selalu tertangkap otomatis.

### 1. Jalankan Codemod Upgrade Resmi

```bash
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:

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

### 2. Atau Instal Paket Secara Manual

Kalau lebih suka kontrol manual daripada codemod otomatis:

```bash
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:

```json
{
  "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](https://nextjs.org/docs/app/guides/upgrading/version-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`:

```tsx
// 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:

```bash
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](/blog/cara-memperbaiki-error-upgrade-nextjs-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](/blog/turbopack-default-nextjs-16-dampaknya).

Perubahan ini melanjutkan arah yang sudah dibahas di [artikel React
Compiler Next.js sebelumnya](/blog/react-compiler-nextjs-panduan-lengkap).
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](/blog/revalidatepath-vs-revalidatetag-nextjs).
- 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](/layanan) 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](/blog/cara-pakai-nextjs-devtools-mcp-ai-assistant) — fitur
  ini tidak tersedia di Next.js 15.