Update & Upgrade Next.js

Analogi: ganti oli vs turun mesin

Merawat project Next.js itu seperti merawat motor. Update patch atau minor itu seperti ganti oli: cepat, rutin, jarang bermasalah, dan motor jadi lebih halus. Upgrade mayor itu seperti turun mesin atau ganti motor baru: butuh persiapan, butuh backup, butuh bengkel yang tepat, dan kadang ada sparepart lama yang ternyata tidak cocok lagi.

Keduanya penting. Motor yang tidak pernah diservis akan rewel di jalan (baca: celah keamanan dan bug yang tidak diperbaiki). Tapi turun mesin sembarangan tanpa persiapan bisa membuat motor yang tadinya jalan malah mogok total.

Kenapa upgrade itu perlu (dan menakutkan)?

Setiap rilis Next.js membawa tiga hal: perbaikan bug, perbaikan keamanan, dan fitur baru. Mengabaikan update berarti menumpuk utang: semakin lama menunda, semakin besar lompatan versi yang harus dilakukan sekaligus, dan semakin besar risiko breaking changes menumpuk jadi satu.

Di sisi lain, ketakutan terhadap upgrade itu wajar: versi mayor boleh mengubah API dan menghapus fitur lama. Itulah kenapa modul ini tidak hanya memberi perintah, tapi juga ritual aman agar upgrade terasa seperti ganti oli, bukan seperti judi.

Update patch dan minor: ganti oli rutin

Untuk update kecil (misalnya 14.0.1 ke 14.0.2, atau 14.0 ke 14.1), perintahnya sederhana:

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

Perhatikan: ketiganya diupdate bersamaan. Next.js, React, dan React DOM adalah trio yang versinya saling terkait. Mengupdate next saja tanpa react sering melahirkan error peer dependency yang pesannya membingungkan, padahal solusinya sebaris itu.

Contoh 1: melihat versi di package.json

Sebelum dan sesudah update, file package.json-mu mencatat versi yang dipakai:

// package.json (sebelum update)
{
  "dependencies": {
    "next": "14.0.4",
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

Setelah perintah di atas dijalankan, angka-angka itu naik ke versi terbaru dan file lock (package-lock.json) ikut diperbarui. Kebiasaan baik: setelah update, jalankan npm run build untuk memastikan project tetap terkompilasi dengan versi baru. Kalau build hijau, update kecil itu aman.

Upgrade mayor: turun mesin dengan codemod

Untuk lompatan versi mayor (misalnya 13 ke 14, atau 14 ke 15), Next.js menyediakan senjata khusus bernama codemod: script migrasi otomatis yang memindai kodemu dan menulis ulang pola lama menjadi pola baru.

npx @next/codemod@latest upgrade latest

Bayangkan codemod seperti montir yang tahu persis baut mana yang berubah posisi di model motor baru: ia mengerjakannya satu per satu secara sistematis, jauh lebih teliti daripada manusia yang find-and-replace manual.

Contoh 2: pola baru yang biasanya datang bersama upgrade

Upgrade mayor sering memperkenalkan API baru yang direkomendasikan. Contoh klasik: pengaturan judul halaman. Di era lama orang memakai komponen <Head>, di App Router modern cukup export objek metadata dari layout:

// app/layout.tsx (cara modern: Metadata API)
import type { Metadata } from "next";

export const metadata: Metadata = {
  title: "Warung Kopi",
  description: "Kopi enak harga kaki lima",
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="id">
      <body>{children}</body>
    </html>
  );
}

Beberapa perubahan seperti ini bahkan punya codemod tersendiri yang mengubahnya otomatis. Pelajarannya: setiap upgrade mayor, baca upgrade guide resmi untuk versi tujuan. Di sana tertulis daftar perubahan, mana yang otomatis oleh codemod, dan mana yang harus diubah manual. Jangan menebak-nebak.

Checklist aman sebelum upgrade

1. Commit dulu semua perubahan (git). Working tree harus bersih. Kalau codemod menghasilkan kekacauan, kamu bisa git checkout dan kembali ke titik aman dalam sedetik.
2. Baca upgrade guide resmi untuk versi tujuan. Bukan changelog mentah, tapi halaman upgrade guide: ia merangkum breaking changes dan cara migrasinya dalam bahasa manusia.
3. Jalankan codemod, lalu npm run build untuk verifikasi. Codemod membantu, bukan sulap. Build yang hijau adalah bukti objektif bahwa migrasi berhasil.
4. Test manual halaman-halaman kritis. Buka halaman login, checkout, atau dashboard: area yang paling mahal kalau rusak. Otomatisasi boleh menyusul, mata manusia tetap wajib.

Catatan teknis: Jangan pernah upgrade mayor di tengah deadline atau langsung di branch main. Selalu di branch terpisah (misalnya upgrade/next-15), lewat build check dan review, baru di-merge. Upgrade adalah pekerjaan terjadwal, bukan aksi spontan.

Kesalahan umum pemula

1. Update next saja tanpa react dan react-dom

SALAH: npm install next@latest sendirian, lalu muncul error peer dependency atau perilaku aneh yang tidak ada di changelog. Frustrasi berjam-jam untuk masalah yang sebenarnya sebaris.

BENAR: Selalu update ketiganya bersamaan seperti perintah di atas. Mereka adalah satu paket yang versinya harus selaras.

2. Menjalankan codemod saat git working tree kotor

SALAH: Ada perubahan yang belum di-commit, codemod dijalankan, hasilnya tercampur antara kerjaanmu dan hasil migrasi. Tidak bisa dibedakan mana yang merusak apa, dan tidak bisa rollback bersih.

BENAR: Commit (atau stash) dulu sampai git status bersih. Codemod hanya boleh berjalan di atas fondasi yang bisa dikembalikan.

3. Upgrade mayor H-1 deadline

SALAH: Demo ke klien besok pagi, malam ini iseng upgrade Next 14 ke 15 "biar kekinian". Paginya build merah dan tidak ada waktu memperbaiki.

BENAR: Jadwalkan upgrade mayor di waktu sepi, di branch terpisah, dengan checklist di atas. Kekinian tidak lebih penting dari project yang jalan.

4. Percaya 100% pada codemod tanpa verifikasi

SALAH: Codemod selesai tanpa error, langsung push ke production. Ternyata ada pola kustom di project yang tidak dikenali codemod dan diam-diam rusak.

BENAR: Codemod adalah asisten, bukan penanggung jawab. npm run build + test manual halaman kritis tetap wajib. Tanggung jawab terakhir selalu di manusia.