Cara Deploy Next.js ke Cloudflare

Kalau kamu mencari cara deploy Next.js ke Cloudflare dan menemukan tutorial yang menyuruh install @cloudflare/next-on-pages lalu bikin project di Cloudflare Pages — tutorial itu sudah usang. Bukan sedikit usang, tapi mengarahkan kamu ke jalur yang sekarang justru dihindari Cloudflare sendiri.

Panduan ini memakai jalur yang benar per 2026: Cloudflare Workers dengan adapter OpenNext. Selain langkah deploy-nya, saya jelaskan juga apa yang berubah, supaya kalau kamu sedang migrasi dari cara lama kamu tahu persis apa yang perlu dibongkar.

Kenapa jalurnya pindah dari Pages ke Workers

Perbedaannya bukan soal selera, tapi soal runtime — dan ini yang bikin banyak orang frustrasi dengan cara lama.

next-on-pages menjalankan aplikasimu di Edge Runtime. Edge Runtime itu versi JavaScript yang sengaja dipangkas: banyak API Node.js tidak tersedia. Konsekuensinya, setiap route yang mau kamu deploy harus ditandai export const runtime = "edge", dan library apa pun yang menyentuh fs, crypto versi Node, atau modul Node lain akan gagal. Banyak yang menyerah di titik ini dan mengira Next.js memang tidak cocok di Cloudflare.

@opennextjs/cloudflare menjalankan aplikasimu di runtime Node.js yang disediakan Workers. Tidak perlu lagi menandai route satu per satu, dan library Node biasa umumnya jalan. Adapter ini mencapai versi 1.0 pada Februari 2026, dan sejak Maret 2026 menjadi jalur yang direkomendasikan tim Next.js sendiri untuk Cloudflare.

Kalau project-mu sudah jalan di Pages dan tidak bermasalah, tidak ada yang meledak besok. Tapi arah pengembangannya jelas, dan migrasi lebih murah dikerjakan sekarang daripada nanti.

Yang perlu disiapkan

• Node.js 20 atau lebih baru. Cek dengan node -v.
• Akun Cloudflare. Paket gratis sudah cukup untuk mencoba.
• Project Next.js yang jalan lokal dengan npm run dev. Kalau belum ada, bikin dulu dengan npx create-next-app@latest.
• Repositori Git kalau nanti mau deploy otomatis. Untuk deploy manual, ini opsional.

Cara tercepat: project baru

Kalau kamu memulai dari nol, satu perintah ini sudah menyiapkan semuanya — project Next.js, adapter, dan konfigurasi Workers sekaligus:

npm create cloudflare@latest -- app-saya --framework=next

Ikuti pertanyaannya, lalu langsung lompat ke bagian Deploy pertama. Sisa bagian di bawah ini untuk kamu yang punya project Next.js yang sudah berjalan.

Langkah 1: Pasang adapter

Dari dalam folder project Next.js kamu:

npm install --save-dev @opennextjs/cloudflare wrangler

@opennextjs/cloudflare yang mengubah hasil build Next.js jadi Worker. wrangler adalah CLI Cloudflare yang mengunggahnya.

Langkah 2: Buat berkas konfigurasi OpenNext

Bikin berkas open-next.config.ts di root project — sejajar dengan package.json:

// open-next.config.ts
import { defineCloudflareConfig } from "@opennextjs/cloudflare";

export default defineCloudflareConfig();

Untuk sekarang biarkan kosong seperti itu. Nanti berkas ini tempat kamu mengatur cache inkremental kalau butuh.

Langkah 3: Buat konfigurasi Wrangler

Bikin wrangler.jsonc di root project:

// wrangler.jsonc
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "app-saya",
  "main": ".open-next/worker.js",
  "compatibility_date": "2026-03-01",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  }
}

Tiga baris yang paling sering jadi sumber error:

• compatibility_flags: ["nodejs_compat"] — ini wajib. Tanpa flag ini, Worker tidak punya akses ke API Node.js dan build kamu akan gagal saat runtime dengan error yang membingungkan.
• compatibility_date — harus 2024-09-23 atau lebih baru supaya nodejs_compat aktif dalam mode yang benar. Isi tanggal hari ini saja.
• main dan assets.directory menunjuk ke folder .open-next/ yang dibuat saat build. Folder ini belum ada sekarang — normal.

Langkah 4: Tambahkan script npm

Buka package.json, tambahkan dua baris di bagian scripts:

"scripts": {
  "dev": "next dev",
  "build": "next build",
  "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview",
  "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy"
}

npm run preview menjalankan aplikasimu di runtime Workers secara lokal. Ini berbeda dari npm run dev yang tetap pakai server Next.js biasa. Selalu cek lewat preview sebelum deploy — di situlah perbedaan runtime muncul.

Langkah 5: Deploy pertama

Login dulu ke Cloudflare dari terminal. Browser akan terbuka untuk otorisasi:

npx wrangler login

Lalu deploy:

npm run deploy

Kalau berhasil, keluarannya kira-kira seperti ini:

Total Upload: 2314.82 KiB / gzip: 480.11 KiB
Uploaded app-saya (8.42 sec)
Deployed app-saya triggers (1.05 sec)
  https://app-saya.akun-kamu.workers.dev
Current Version ID: 4f2a...

Buka URL .workers.dev itu. Aplikasi Next.js kamu sudah live.

Langkah 6: Deploy otomatis tiap push

Deploy manual cocok untuk mencoba, tapi tidak untuk kerja sehari-hari. Ada dua cara membuatnya otomatis.

Lewat dashboard Cloudflare

Di dashboard Cloudflare, masuk ke Workers & Pages, pilih Worker kamu, buka tab Settings lalu bagian Build, dan hubungkan repositori Git. Isi build command dengan npm run deploy. Setiap push ke branch utama akan memicu deploy.

Lewat GitHub Actions

Kalau kamu ingin kontrol lebih, pakai workflow. Bikin .github/workflows/deploy.yml:

name: Deploy ke Cloudflare Workers

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Buat API token di dashboard Cloudflare lewat My Profile → API Tokens dengan template Edit Cloudflare Workers, lalu simpan token dan Account ID sebagai repository secret di GitHub.

Langkah 7: Pasang domain sendiri

Di dashboard, buka Worker kamu → Settings → Domains & Routes → Add → Custom domain. Masukkan domain atau subdomain yang ingin dipakai.

Kalau domainnya sudah dikelola Cloudflare, DNS record dan sertifikat SSL dibuat otomatis dalam hitungan menit. Kalau nameserver-mu masih di registrar lain, kamu perlu memindahkannya ke Cloudflare dulu. Prosesnya saya bahas terpisah di panduan custom domain dan SSL.

Kalau kamu migrasi dari next-on-pages

Urutan yang paling aman:

1. Copot paket lama. npm uninstall @cloudflare/next-on-pages.
2. Hapus semua export const runtime = "edge" dari route kamu. Ini tidak lagi diperlukan, dan justru membatasi.
3. Hapus konfigurasi lama — biasanya berupa berkas wrangler.toml versi Pages atau setelan build di project Pages.
4. Ikuti langkah 1–5 di atas untuk memasang jalur baru.
5. Deploy ke URL .workers.dev dulu, uji betul-betul, baru pindahkan custom domain-nya. Jangan pindah domain sebelum yakin.

Yang paling sering terlewat adalah langkah kedua. Sisa runtime = "edge" membuat route tetap berjalan di Edge Runtime meski adapternya sudah baru, dan kamu akan bingung kenapa library Node masih error.

Masalah yang sering muncul

Error "Node.js Compatibility Error"

Artinya nodejs_compat belum aktif, atau compatibility_date terlalu lawas. Pastikan dua baris ini ada di wrangler.jsonc dan tanggalnya minimal 2024-09-23:

  "compatibility_date": "2026-03-01",
  "compatibility_flags": ["nodejs_compat"],

Worker melebihi batas ukuran

Paket gratis membatasi ukuran Worker (setelah kompresi gzip) sekitar 3 MB, berbayar 10 MB. Kalau kena, biasanya penyebabnya satu-dua dependensi besar yang ikut ter-bundle. Periksa apakah ada library berat yang sebetulnya cuma dipakai di build time — pindahkan ke devDependencies, atau impor secara dinamis supaya tidak masuk bundle utama.

Halaman muncul tapi gambar dan CSS tidak

Hampir selalu karena blok assets di wrangler.jsonc salah atau tidak ada. directory harus persis .open-next/assets dan binding harus ASSETS huruf besar semua.

Jalan di lokal, error setelah deploy

Ini gejala klasik menguji dengan npm run dev saja. next dev memakai server Node biasa, bukan runtime Workers. Selalu uji dengan npm run preview — perintah itu menjalankan runtime yang sama dengan produksi, jadi selisihnya ketahuan sebelum deploy.

Environment variable tidak terbaca

Variabel dari .env.local tidak ikut terkirim. Untuk nilai biasa, tambahkan blok vars di wrangler.jsonc. Untuk nilai rahasia, pakai npx wrangler secret put NAMA_VARIABEL supaya tidak tersimpan di repositori.

Ringkasan

Enam berkas dan perintah yang menentukan:

Ekosistem ini masih bergerak cepat — Cloudflare sedang membangun adapter resminya sendiri di atas OpenNext selama 2026. Kalau ada perintah di panduan ini yang tidak cocok dengan versi yang kamu pasang, cek dokumentasi OpenNext untuk Cloudflare sebagai sumber paling mutakhir.

Kalau deploy-mu gagal dengan pesan yang tidak dibahas di sini, kemungkinan besar ada di kumpulan error deploy paling umum.

Baru mulai menerbitkan situs? Gambaran menyeluruhnya ada di panduan lengkap deploy website, dan perbandingan platformnya di Cloudflare vs Vercel.