Deploy Next.js ke Vercel dapat dilakukan langsung dari repository Git tanpa mengelola server secara manual. Vercel akan mengambil kode dari repository, menjalankan proses build, membuat deployment untuk branch atau pull request, lalu menyediakan URL untuk menguji aplikasi.

Panduan ini mencakup alur lengkap: menghubungkan repository, memeriksa konfigurasi build, memilih production branch, mengatur environment variables untuk Development, Preview, dan Production, membaca log deployment, kemudian menambahkan custom domain dengan DNS dan HTTPS otomatis.

Prasyarat sebelum deploy

Siapkan beberapa hal berikut sebelum membuat project di Vercel:

  • Project Next.js yang dapat dijalankan dan di-build secara lokal.

  • Repository Git di GitHub, GitLab, atau Bitbucket.

  • Akun Vercel yang dapat mengakses repository tersebut.

  • Akses untuk mengubah DNS pada penyedia domain.

  • Environment variables yang diperlukan aplikasi, seperti URL API atau kredensial layanan eksternal.

Uji proses build secara lokal terlebih dahulu. Gunakan package manager yang sesuai dengan lockfile repository:

npm install
npm run build
npm run start

Jika repository menggunakan pnpm-lock.yaml atau yarn.lock, gunakan pnpm atau Yarn agar versi dependency yang dipakai tetap konsisten. Pastikan script build tersedia di package.json, misalnya:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Deploy Next.js ke Vercel dari repository Git

1. Import repository

  1. Masuk ke dashboard Vercel.

  2. Pilih Add New Project atau opsi untuk mengimpor project.

  3. Hubungkan akun Git yang digunakan, lalu pilih repository Next.js.

  4. Periksa nama project dan pilih team atau scope yang sesuai.

  5. Klik opsi untuk melanjutkan proses deployment.

Vercel biasanya mendeteksi Next.js secara otomatis. Pada konfigurasi standar, framework yang dipilih adalah Next.js, build command menggunakan script build dari project, dan output directory ditangani oleh framework. Jangan mengubah output directory ke folder statis seperti out kecuali aplikasi memang dikonfigurasi untuk static export.

2. Periksa konfigurasi build

Pada halaman konfigurasi project, periksa beberapa nilai berikut:

  • Framework Preset: Next.js.

  • Root Directory: direktori yang berisi package.json. Untuk monorepo, pilih folder aplikasi Next.js.

  • Build Command: biasanya npm run build, atau command yang sesuai dengan package manager project.

  • Install Command: gunakan command yang konsisten dengan lockfile repository.

  • Output Directory: gunakan nilai default Next.js kecuali aplikasi memakai konfigurasi khusus.

  • Node.js Version: pilih versi yang kompatibel dengan dependency dan pengujian lokal project.

Jika project berada di dalam monorepo, kesalahan Root Directory adalah salah satu penyebab umum build gagal. Vercel harus diarahkan ke direktori yang benar agar dapat menemukan package.json, lockfile, dan konfigurasi Next.js.

3. Atur branch production

Vercel membedakan deployment production dan preview. Branch yang dipilih sebagai Production Branch akan menghasilkan deployment production ketika perubahan berhasil di-build. Branch lain dan pull request umumnya digunakan untuk preview deployment.

Pilih branch utama yang benar, misalnya main atau branch release yang memang menjadi sumber rilis. Pengaturannya dapat diperiksa kembali di pengaturan Git project Vercel. Sebelum mengubah branch production, pastikan branch tersebut memiliki konfigurasi build dan environment variables yang lengkap.

Catatan: deployment preview berguna untuk menguji pull request tanpa mengganti deployment production. Jangan menganggap semua environment variable production otomatis tersedia di preview.

Environment variables untuk Development, Preview, dan Production

Environment variables di Vercel memiliki scope yang berbeda. Secara umum, gunakan pembagian berikut:

  • Development: dipakai saat menjalankan project melalui workflow development yang terhubung ke Vercel atau saat variabel disalin ke lingkungan lokal.

  • Preview: dipakai pada deployment dari branch non-production dan pull request.

  • Production: dipakai pada deployment dari production branch.

Tambahkan variabel melalui pengaturan project pada bagian Environment Variables, lalu pilih environment yang relevan. Contoh variabel server-side:

DATABASE_URL=postgresql://user:password@host:5432/app
API_BASE_URL=https://api.example.com

Variabel yang diperlukan browser harus diawali NEXT_PUBLIC_, misalnya:

NEXT_PUBLIC_APP_URL=https://example.com

Namun, awalan tersebut berarti nilainya dapat masuk ke bundle client dan terlihat oleh pengguna. Jangan menaruh password, private API key, token database, atau credential rahasia pada variabel NEXT_PUBLIC_.

Contoh penggunaan di kode server:

const apiBaseUrl = process.env.API_BASE_URL;

if (!apiBaseUrl) {
  throw new Error("API_BASE_URL belum dikonfigurasi");
}

Setelah menambah atau mengubah environment variable, lakukan deployment baru. Nilai tersebut tidak selalu diterapkan pada deployment lama secara otomatis. Periksa juga apakah variabel dibuat untuk scope yang benar; aplikasi dapat berhasil di Preview tetapi gagal di Production karena variabel Production belum diisi.

Memeriksa hasil deployment dan log

Setelah deployment selesai, buka halaman deployment di dashboard Vercel. Periksa status build, URL deployment, commit yang digunakan, dan branch sumbernya. Gunakan URL preview untuk menguji aplikasi sebelum mengarahkannya ke domain utama.

Log build

Build log menampilkan proses instalasi dependency, eksekusi build, dan error dari Next.js. Cari bagian pertama yang menunjukkan error sebenarnya, bukan hanya pesan bahwa deployment gagal. Beberapa penyebab yang sering ditemukan:

  • Dependency tidak kompatibel dengan versi Node.js yang digunakan.

  • Script build tidak tersedia atau command salah.

  • Environment variable wajib belum disediakan.

  • Import memiliki perbedaan huruf besar-kecil sehingga gagal pada sistem Linux.

  • Root Directory menunjuk ke folder yang salah.

  • TypeScript error atau lint error menghentikan proses build.

Runtime dan function logs

Jika build berhasil tetapi aplikasi error saat dibuka, periksa runtime logs atau logs function. Log ini membantu menemukan error pada route server, API route, middleware, akses database, dan integrasi layanan eksternal.

Hindari mencetak token atau credential ke log. Untuk debugging, log informasi yang aman seperti nama route, status operasi, atau identifier request yang tidak bersifat rahasia.

Menambahkan custom domain ke project Vercel

1. Tambahkan domain di Vercel

  1. Buka project di dashboard Vercel.

  2. Masuk ke bagian pengaturan domain.

  3. Tambahkan nama domain, misalnya example.com atau www.example.com.

  4. Ikuti instruksi verifikasi yang ditampilkan Vercel.

Tambahkan domain yang benar-benar akan digunakan pengguna. Jika aplikasi dapat diakses melalui apex domain dan www, tambahkan keduanya lalu tentukan salah satu sebagai domain utama. Vercel dapat mengarahkan domain alternatif ke domain utama setelah konfigurasi selesai.

2. Konfigurasi DNS untuk apex domain

Apex domain adalah domain tanpa subdomain, seperti example.com. Pada penyedia DNS, apex biasanya direpresentasikan dengan simbol @. Vercel akan menampilkan record yang harus dibuat; gunakan nilai dari dashboard tersebut karena detail dapat berubah sesuai konfigurasi akun dan domain.

Konfigurasi yang umum untuk apex domain adalah record A yang mengarah ke alamat IP Vercel yang direkomendasikan. Beberapa penyedia DNS mendukung record ALIAS atau ANAME, yang juga dapat digunakan apabila direkomendasikan oleh penyedia DNS.

Type: A
Name: @
Value: [alamat IP yang ditampilkan Vercel]
TTL: Auto atau nilai default

Jangan membuat beberapa record A yang saling bertentangan. Jika domain menggunakan layanan proxy atau CDN dari penyedia DNS, ikuti instruksi Vercel dan periksa apakah mode proxy tersebut kompatibel.

3. Konfigurasi DNS untuk subdomain

Untuk subdomain seperti www.example.com, record yang umum digunakan adalah CNAME. Nama record biasanya www, sedangkan target harus mengikuti nilai yang diberikan Vercel.

Type: CNAME
Name: www
Value: [target CNAME yang ditampilkan Vercel]
TTL: Auto atau nilai default

Untuk subdomain lain, misalnya app.example.com, gunakan nama app dan target yang diberikan dashboard. Hapus record lama dengan nama yang sama jika record tersebut menyebabkan konflik. Satu hostname tidak boleh memiliki konfigurasi CNAME yang bertentangan.

4. Verifikasi domain

Setelah record DNS dibuat, kembali ke halaman domain di Vercel dan jalankan pemeriksaan atau verifikasi. Vercel akan mengecek apakah DNS mengarah ke konfigurasi yang benar. Jika domain digunakan oleh project lain atau memerlukan pembuktian kepemilikan, Vercel dapat meminta record TXT tambahan. Tambahkan record TXT tersebut persis seperti yang ditampilkan, termasuk nama dan nilainya.

DNS tidak selalu berubah seketika. Resolver, registrar, dan nilai TTL dapat menyebabkan hasil berbeda selama masa propagasi. Anda dapat memeriksa record dengan perintah berikut:

dig example.com A
dig www.example.com CNAME
nslookup example.com

Hasil pemeriksaan dari satu jaringan belum tentu sama dengan jaringan lain karena cache DNS. Tunggu hingga record terlihat secara konsisten sebelum menyimpulkan bahwa konfigurasi gagal.

HTTPS otomatis di Vercel

Setelah domain berhasil ditambahkan dan DNS mengarah ke Vercel, Vercel biasanya menyediakan sertifikat TLS secara otomatis. Status sertifikat dapat diperiksa pada halaman domain project. Setelah aktif, akses aplikasi menggunakan https://.

Jika HTTPS belum aktif, pastikan domain sudah terverifikasi, DNS tidak masih mengarah ke hosting lama, dan tidak ada record yang bertentangan. Jangan membuat sertifikat manual di server aplikasi karena terminasi TLS dikelola oleh infrastruktur Vercel.

Setelah HTTPS aktif, periksa juga:

  • Redirect dari HTTP ke HTTPS berjalan sesuai kebutuhan.

  • URL canonical dan konfigurasi metadata menggunakan hostname yang benar.

  • Cookie sensitif memakai atribut Secure jika memang digunakan melalui HTTPS.

  • Webhook atau OAuth provider telah memasukkan URL HTTPS yang baru ke allowlist.

Troubleshooting deployment dan domain

Build gagal di Vercel tetapi berhasil lokal

  • Bandingkan versi Node.js dan package manager antara lokal dengan konfigurasi project.

  • Pastikan lockfile ikut di-commit ke repository.

  • Periksa perbedaan huruf besar-kecil pada nama file dan import.

  • Pastikan semua environment variables tersedia pada scope Deployment yang sedang diuji.

  • Periksa Root Directory jika project menggunakan monorepo.

  • Jalankan build dengan mode yang sedekat mungkin dengan CI, bukan hanya next dev.

Domain masih menampilkan project atau hosting lama

Periksa record A, AAAA, dan CNAME. Record AAAA yang tersisa dapat menyebabkan sebagian pengguna diarahkan ke server IPv6 lama. Hapus record yang tidak diperlukan atau ikuti instruksi penyedia domain. Pastikan domain tidak sedang diarahkan melalui redirect registrar yang berbeda.

DNS belum propagasi

Gunakan dig atau layanan pemeriksaan DNS dari beberapa lokasi. Jangan mengubah record berulang kali tanpa memeriksa hasil sebelumnya karena perubahan tambahan dapat memperpanjang proses debugging. Setelah record yang benar terlihat, tunggu cache DNS berakhir dan ulangi verifikasi di Vercel.

Environment variable tidak terbaca

Pastikan nama variabel sama persis, termasuk kapitalisasi, dan scope-nya sesuai. Variabel server-side tidak boleh dibaca dari komponen client. Jika nilai baru saja diubah, buat deployment baru agar aplikasi dibangun dengan konfigurasi terbaru.

Checklist sebelum production

  • Build production berhasil tanpa error.

  • Production Branch menunjuk ke branch rilis yang benar.

  • Environment variables Development, Preview, dan Production sudah dipisahkan sesuai kebutuhan.

  • Preview deployment telah diuji pada route utama, form, API, autentikasi, dan integrasi database.

  • Apex domain dan subdomain sudah memiliki record DNS yang direkomendasikan Vercel.

  • Domain telah terverifikasi dan sertifikat HTTPS berstatus aktif.

  • Webhook, OAuth callback, CORS, sitemap, dan canonical URL menggunakan domain baru.

  • Log deployment dan runtime tidak membocorkan data rahasia.

Dengan alur ini, repository Git menjadi sumber perubahan, Vercel menangani build dan deployment, sedangkan DNS menghubungkan domain publik ke deployment yang benar. Memisahkan environment variables berdasarkan Development, Preview, dan Production membantu mencegah konfigurasi pengujian terbawa ke aplikasi production.