Migrasi middleware.ts ke proxy.ts Next.js 16

Migrasi middleware.ts ke proxy.ts di Next.js 16 dilakukan dengan mengganti nama file jadi proxy.ts, mengganti nama fungsi yang diekspor dari middleware jadi proxy, dan menyesuaikan flag konfigurasi yang mengandung kata "middleware" jadi "proxy". Logika di dalamnya (NextRequest, NextResponse, config.matcher) tetap sama, kecuali proyek yang masih butuh runtime edge, karena proxy.ts hanya mendukung runtime nodejs.

Ringkasan cepat:

1. Tiga perubahan inti: nama file (middleware.ts ke proxy.ts), nama fungsi yang diekspor (middleware ke proxy), dan flag konfigurasi terkait (skipMiddlewareUrlNormalize ke skipProxyUrlNormalize).
2. Logika di dalam fungsi tidak berubah sama sekali: NextRequest, NextResponse, dan config.matcher tetap dipakai persis seperti sebelumnya.
3. Perbedaan paling krusial: proxy.ts hanya mendukung runtime nodejs, sedangkan runtime edge hanya tersedia di middleware.ts yang lama.
4. Codemod resmi npx @next/codemod@canary upgrade latest bisa otomatis merename file, fungsi, dan flag konfigurasi, tapi proyek dengan runtime edge wajib dicek manual.
5. middleware.ts masih berfungsi di Next.js 16 (deprecated, belum dihapus), jadi migrasi bisa dilakukan bertahap, bukan mendadak wajib di hari yang sama dengan upgrade versi.

Kenapa Next.js Mengganti Nama middleware.ts Jadi proxy.ts?#

Penggantian nama ini bukan sekadar kosmetik. Menurut dokumentasi resmi upgrade ke Next.js 16, nama "middleware" sering disalahartikan sebagai tempat menjalankan logika berat atau mengakses database langsung, padahal fungsi file ini di Next.js selalu terbatas pada penanganan request di batas jaringan (network boundary), seperti redirect, rewrite, dan modifikasi header sebelum request mencapai route handler. Nama "proxy" dipilih untuk mencerminkan peran aslinya secara lebih akurat.

Apa yang Sebenarnya Berubah, dan Apa yang Tidak?#

Hanya tiga hal yang berubah:

• Nama file: middleware.ts (atau .js) menjadi proxy.ts/proxy.js.
• Nama fungsi yang diekspor: dari middleware menjadi proxy.
• Nama flag konfigurasi yang mengandung kata "middleware", misalnya skipMiddlewareUrlNormalize di next.config.ts menjadi skipProxyUrlNormalize.

Yang tidak berubah: NextRequest, NextResponse, cara membaca cookies/header, dan konfigurasi config.matcher untuk menentukan rute mana yang terkena proxy. Kalau sebelumnya punya middleware untuk redirect berdasarkan locale, misalnya, isi fungsinya tetap identik, cuma nama file dan fungsinya yang berganti:

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
export function middleware(request: NextRequest) {
  const locale = request.cookies.get("locale")?.value ?? "id";
  const response = NextResponse.next();
  response.headers.set("x-locale", locale);
  return response;
}
 
export const config = {
  matcher: ["/dashboard/:path*"],
};

import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";
 
export function proxy(request: NextRequest) {
  const locale = request.cookies.get("locale")?.value ?? "id";
  const response = NextResponse.next();
  response.headers.set("x-locale", locale);
  return response;
}
 
export const config = {
  matcher: ["/dashboard/:path*"],
};

Bagaimana Cara Migrasi Secara Manual, Langkah demi Langkah?#

1. Rename file. Jalankan mv middleware.ts proxy.ts (atau .js) di root proyek, persis sejajar dengan folder app/.
2. Rename fungsi yang diekspor. Ubah export function middleware(...) menjadi export function proxy(...). Dokumentasi resmi tetap menyarankan nama fungsi proxy walaupun dipakai lewat export default.
3. Cek flag konfigurasi di next.config.ts. Cari flag apa pun yang mengandung kata "middleware" (contoh skipMiddlewareUrlNormalize) dan ganti ke penamaan baru (skipProxyUrlNormalize).
4. Jalankan npm run build untuk memastikan tidak ada referensi lama ke middleware.ts yang tertinggal (import manual, test, atau dokumentasi internal proyek).

Cara lebih cepat untuk proyek yang tidak memakai runtime edge: jalankan codemod resmi npx @next/codemod@canary upgrade latest, yang otomatis menangani rename file, fungsi, dan flag konfigurasi sekaligus sebagai bagian dari upgrade ke Next.js 16.

Kapan Harus Tetap Pakai middleware.ts, Bukan proxy.ts?#

Satu pengecualian penting: runtime edge tidak didukung di proxy.ts. Runtime proxy.ts tetap nodejs dan tidak bisa dikonfigurasi ke edge. Proyek yang benar-benar membutuhkan runtime edge (misalnya karena dependency tertentu atau pertimbangan latensi regional) harus tetap memakai middleware.ts untuk saat ini, sambil menunggu arahan lanjutan soal runtime edge yang dijanjikan tim Next.js di rilis minor berikutnya.

Checklist resmi migrasi Next.js 16 bahkan menegaskan poin ini secara eksplisit: "Edge middleware is not blindly renamed to proxy" - artinya menjalankan codemod begitu saja tanpa memeriksa runtime yang dipakai bisa berisiko mematahkan proyek yang bergantung pada edge. Kalau situs atau aplikasi memakai runtime default (nodejs), seperti kebanyakan proyek Next.js yang di-deploy ke VPS sendiri (lihat cara deploy Next.js ke VPS tanpa Vercel), migrasi ke proxy.ts aman dilakukan langsung tanpa penyesuaian tambahan.

Ringkasan: Rename File dan Fungsi Saja, Tapi Cek Runtime Edge Dulu#

• Migrasi middleware.ts ke proxy.ts di Next.js 16 pada dasarnya cuma rename file, rename fungsi, dan rename flag konfigurasi yang mengandung kata "middleware" - logika di dalamnya tidak berubah.
• Satu pengecualian yang wajib dicek lebih dulu: proxy.ts hanya mendukung runtime nodejs, jadi proyek yang memakai runtime edge harus tetap memakai middleware.ts untuk saat ini.
• Codemod resmi mempercepat migrasi untuk kasus umum, tapi dokumentasi resmi sendiri menegaskan verifikasi manual tetap perlu untuk proyek dengan runtime edge.
• Kalau butuh bantuan mengaudit atau memigrasikan proyek Next.js ke versi terbaru secara menyeluruh, ini termasuk cakupan jasa web development yang ditawarkan.