Turbopack sudah menjadi bundler default next build sejak Next.js 16, tanpa perlu flag atau konfigurasi tambahan. Kalau proyek punya fungsi webpack() custom di next.config.js, build akan gagal dengan sengaja sampai config itu dipindah ke opsi turbopack atau build dijalankan dengan flag --webpack sebagai fallback sementara.
Ringkasan cepat:
- Sejak Next.js 16, Turbopack otomatis dipakai untuk
next devdannext build, tanpa flag--turbopackyang dulu wajib di Next.js 15. - Kalau
next.config.js/.tsmasih punya fungsiwebpack()custom,next buildakan gagal dengan sengaja, bukan diam-diam mengabaikan config itu. - Loader webpack custom perlu dipindah ke
turbopack.rules, memetakan ekstensi file ke daftar loader (string biasa, atau object{ loader, options }untuk loader yang butuh opsi tambahan). - Loader yang bergantung pada fitur webpack seperti
importModule,loadModule, atauemitFilebelum didukung Turbopack. - Flag
--webpacktetap tersedia sebagai fallback sah untuk migrasi bertahap, tanpa perlu downgrade versi Next.js.
Apa yang Berubah dari Next.js 15 ke Next.js 16 soal Turbopack?
Di Next.js 15, Turbopack untuk next build masih berstatus beta dan harus diaktifkan manual lewat flag --turbopack di script package.json. Mulai Next.js 16, Turbopack stabil dan otomatis dipakai baik untuk next dev maupun next build, sehingga script cukup ditulis polos:
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}Flag --turbopack yang dulu wajib sekarang tidak diperlukan lagi. Perubahan default ini terkonfirmasi di dokumentasi resmi migrasi Next.js 16.
Kapan Build Justru Gagal Setelah Upgrade?
Kalau next.config.js atau next.config.ts masih punya fungsi webpack() custom, next build di Next.js 16 akan gagal dengan sengaja alih-alih diam-diam mengabaikan konfigurasi itu. Menurut dokumentasi resmi, ini disengaja untuk mencegah perbedaan perilaku production yang tidak disadari, karena Turbopack tidak pernah membaca opsi webpack() sama sekali.
Sebagai ilustrasi konkret: next.config.ts situs ini sendiri masih memakai fungsi webpack() custom untuk mendaftarkan plugin build Velite (integrasi konten MDX). Kalau situs ini di-upgrade ke Next.js 16 hari ini, next build akan gagal persis dengan error yang sama sampai plugin itu dipindah ke bentuk yang kompatibel Turbopack atau build dijalankan dengan flag --webpack.
If your project has a custom
webpackconfiguration and you runnext build(which now uses Turbopack by default), the build will fail to prevent misconfiguration issues.(Next.js 16 upgrade guide, nextjs.org/docs/app/guides/upgrading/version-16)
Bagaimana Cara Migrasi Custom Webpack Loader ke turbopack.rules?
Loader webpack yang sebelumnya didaftarkan lewat fungsi webpack() perlu dipindah ke key turbopack.rules di next.config.ts, dengan pola memetakan ekstensi file ke daftar loader. Contoh resmi untuk loader @svgr/webpack (mengubah import .svg jadi komponen React):
import type { NextConfig } from "next";
const nextConfig: NextConfig = {
turbopack: {
rules: {
"*.svg": {
loaders: ["@svgr/webpack"],
as: "*.js",
},
},
},
};
export default nextConfig;Untuk loader yang butuh opsi tambahan, gunakan bentuk object berisi loader dan options, bukan string biasa:
turbopack: {
rules: {
"*.svg": {
loaders: [
{
loader: "@svgr/webpack",
options: { icon: true },
},
],
as: "*.js",
},
},
},Menurut referensi konfigurasi Turbopack resmi, loader yang sudah teruji kompatibel antara lain babel-loader, @svgr/webpack, svg-inline-loader, yaml-loader, string-replace-loader, raw-loader, sass-loader, dan graphql-tag/loader. Loader lain kemungkinan besar tetap jalan, tapi hanya sebagian API loader webpack yang diimplementasikan Turbopack, jadi loader yang bergantung pada fitur seperti importModule, loadModule, atau emitFile belum didukung.
The following loaders have been tested to work with Turbopack's webpack loader implementation, but many other webpack loaders should work as well even if not listed here.
(Turbopack config reference, nextjs.org/docs/app/api-reference/config/next-config-js/turbopack)
Bagaimana Cara Memverifikasi Turbopack Benar-Benar Dipakai di Production Build?
Cara paling sederhana adalah membaca output terminal saat next build berjalan. Next.js akan menampilkan indikator Turbopack di baris ringkasan build, berbeda dari output Webpack klasik. Kalau build gagal karena config webpack() terdeteksi, pesan errornya eksplisit menyebut bahwa Turbopack tidak bisa memproses opsi tersebut, bukan gagal generik tanpa penjelasan.
Verifikasi kedua yang lebih aman untuk tim yang ragu: jalankan build dua kali secara terpisah, satu dengan default (Turbopack) dan satu lagi dengan flag --webpack, lalu bandingkan output .next/ (ukuran bundle, jumlah chunk) untuk memastikan tidak ada regresi fungsional sebelum benar-benar melepas fallback Webpack.
Bagaimana Cara Fallback ke Webpack Kalau Migrasi Belum Selesai?
Kalau sebagian loader belum sempat dipindah, Next.js tetap menyediakan opsi memakai Webpack secara eksplisit lewat flag --webpack, tanpa perlu downgrade versi Next.js:
{
"scripts": {
"dev": "next dev",
"build": "next build --webpack",
"start": "next start"
}
}Pola ini cocok untuk migrasi bertahap: development tetap pakai Turbopack (lebih cepat untuk iterasi harian), sementara production build sementara tetap Webpack sampai semua loader custom selesai dipetakan ke turbopack.rules. Setelah migrasi loader tuntas dan sudah diverifikasi, flag --webpack tinggal dihapus supaya production build ikut memakai Turbopack sepenuhnya.
Turbopack (Default) vs Webpack (Fallback): Perbandingan Script
| Aspek | Turbopack (default) | Webpack (fallback) |
|---|---|---|
Script dev | next dev | next dev |
Script build | next build | next build --webpack |
Script start | next start | next start |
| Loader custom | Wajib dipetakan ke turbopack.rules | Tetap pakai fungsi webpack() lama |
| Status di Next.js 16 | Default, tanpa flag tambahan | Opsi manual, perlu flag --webpack eksplisit |
Ringkasan: turbopack.rules dan --webpack sebagai Dua Jalur Migrasi Loader
- Turbopack sudah default untuk
next buildsejak Next.js 16, tanpa flag--turbopackyang dulu wajib di Next.js 15. - Proyek dengan fungsi
webpack()custom dinext.config.js/.tsakan gagal build dengan sengaja sampai dipindah keturbopack.rulesatau dijalankan dengan flag--webpack. - Loader dengan opsi tambahan memakai bentuk object
{ loader, options }, bukan string biasa, di dalamturbopack.rules. - Flag
--webpacktetap tersedia sebagai fallback sah untuk migrasi bertahap, bukan cuma solusi darurat. - Proses migrasi Next.js 16 lengkap, termasuk perubahan API caching lain, sudah dibahas di cara upgrade Next.js 15 ke Next.js 16 langkah demi langkah. Butuh bantuan migrasi proyek Next.js secara menyeluruh? Layanan web development mencakup audit dan eksekusi upgrade seperti ini.
