Cara Deploy SvelteKit ke Vercel

SvelteKit ke Vercel termasuk deploy yang paling mulus — sebagian besar ditangani otomatis. Tapi ada satu keputusan yang menentukan banyak hal di kemudian hari: adapter mana yang kamu pakai. Salah pilih di sini, dan kamu akan menemui error yang penyebabnya sulit ditebak.

Panduan ini mulai dari keputusan itu.

adapter-auto atau adapter-vercel?

Project SvelteKit baru datang dengan @sveltejs/adapter-auto. Adapter ini mendeteksi tempat kamu deploy lalu memilih adapter yang sesuai — di Vercel, ia memakai adapter-vercel.

Untuk sekadar mencoba, itu sudah cukup. Tapi untuk project yang serius, pasang adapter-vercel secara langsung. Dua alasannya:

• Kamu tidak bisa mengatur apa pun lewat adapter-auto. Pilihan runtime, region, dan ISR hanya tersedia kalau adapternya dipasang eksplisit.
• Build lokal jadi tidak dapat diandalkan. Di luar Vercel, adapter-auto tidak tahu harus jadi apa, jadi npm run build di laptopmu berperilaku berbeda dari di server.

Yang perlu disiapkan

• Node.js 20 atau lebih baru — cek dengan node -v.
• Akun Vercel, paket Hobby gratis sudah cukup.
• Project SvelteKit yang jalan dengan npm run dev. Belum ada? Bikin dengan npx sv create app-saya.
• Repositori Git di GitHub, GitLab, atau Bitbucket.

Langkah 1: Pasang adapter Vercel

npm install --save-dev @sveltejs/adapter-vercel

Lalu buka svelte.config.js dan ganti impor adapternya:

import adapter from '@sveltejs/adapter-vercel';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
export default {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter()
  }
};

Kalau @sveltejs/adapter-auto masih terpasang, copot saja supaya tidak membingungkan:

npm uninstall @sveltejs/adapter-auto

Langkah 2: Pilih runtime

Secara bawaan, adapter memakai runtime Node.js — dan itu pilihan yang benar untuk hampir semua kasus. Kamu bisa mengaturnya eksplisit:

    adapter: adapter({
      runtime: 'nodejs22.x'
    })

Ada juga runtime 'edge', yang menjalankan kodemu lebih dekat ke pengguna dengan waktu mulai lebih cepat. Tapi Edge Runtime memangkas banyak API Node.js, jadi library yang menyentuh fs, crypto versi Node, atau modul Node lain akan gagal.

Langkah 3: Deploy lewat Git

Cara yang dianjurkan, karena setelah ini semuanya berjalan sendiri.

1. Push project-mu ke GitHub, GitLab, atau Bitbucket.
2. Buka vercel.com/new, pilih repositorinya.
3. Vercel mendeteksi SvelteKit otomatis. Biarkan semua setelan build apa adanya — jangan diubah kecuali kamu tahu persis kenapa.
4. Klik Deploy.

Satu-dua menit kemudian situsmu live di alamat .vercel.app. Sejak titik ini, setiap push ke branch utama otomatis jadi deploy produksi, dan setiap pull request dapat URL preview sendiri.

Alternatif: lewat CLI

npm install -g vercel
vercel login
vercel

Untuk langsung ke produksi, tambahkan --prod. Cara ini praktis untuk uji cepat, tapi tidak memberimu deploy otomatis.

Langkah 4: Environment variable

SvelteKit membedakan variabel rahasia dan variabel publik lewat modul impornya — dan ini salah satu hal yang paling rapi di SvelteKit.

// Rahasia — hanya bisa diimpor di kode sisi server
import { DATABASE_URL } from '$env/static/private';

// Publik — boleh dipakai di komponen
import { PUBLIC_API_URL } from '$env/static/public';

Variabel yang mau dipakai di browser harus diawali PUBLIC_. Yang tanpa prefiks hanya bisa diimpor dari $env/static/private, dan SvelteKit akan menolak build kalau kamu mencoba mengimpornya di komponen — pengaman yang bagus.

Daftarkan nilainya di dashboard Vercel lewat Settings → Environment Variables. Berkas .env lokalmu tidak ikut ter-deploy.

Langkah 5: Prerender halaman yang statis

Halaman yang isinya sama untuk semua orang sebaiknya dirender saat build, bukan tiap permintaan. Lebih cepat dan tidak menghabiskan kuota function.

Tambahkan di +page.js atau +page.server.js:

export const prerender = true;

Untuk membuatnya berlaku ke seluruh situs, taruh di src/routes/+layout.js, lalu matikan per halaman yang memang dinamis dengan export const prerender = false;.

Langkah 6: ISR untuk halaman yang jarang berubah

ISR menyajikan halaman dari cache dan membangunnya ulang berkala. Cocok untuk daftar artikel atau katalog produk — data yang berubah, tapi tidak tiap detik.

export const config = {
  isr: {
    expiration: 600
  }
};

Angka 600 berarti halaman disajikan dari cache maksimal 10 menit sebelum dibangun ulang. Pengguna selalu mendapat respons instan, dan kamu tidak membebani database tiap kunjungan.

Langkah 7: Pasang domain sendiri

Di dashboard Vercel, buka project → Settings → Domains → masukkan domainmu. Vercel akan menampilkan record DNS yang perlu ditambahkan:

Sertifikat SSL diterbitkan otomatis setelah DNS terverifikasi. Detailnya ada di panduan custom domain dan SSL.

Masalah yang sering muncul

Error "Cannot find module" untuk modul Node

Kamu memakai runtime: 'edge' tapi ada kode yang butuh API Node.js. Kembalikan ke runtime Node dengan menghapus baris runtime atau menggantinya jadi 'nodejs22.x'.

Build jalan lokal, gagal di Vercel

Kalau kamu masih pakai adapter-auto, inilah gejala klasiknya — adapter berperilaku berbeda di dua tempat. Pasang adapter-vercel secara eksplisit seperti di langkah 1.

Error prerender: "Cannot access window"

Ada kode yang menyentuh window atau document saat prerender, padahal di situ tidak ada browser. Pindahkan ke onMount, atau bungkus dengan pengecekan browser dari SvelteKit:

import { browser } from '$app/environment';

if (browser) {
  // kode yang butuh browser
}

Halaman 404 padahal rutenya ada

Kalau rutenya dinamis seperti /blog/[slug] dan kamu mengaktifkan prerender, SvelteKit perlu tahu daftar slug-nya. Ekspor fungsi entries di +page.server.js yang mengembalikan semua kemungkinan nilai, atau matikan prerender untuk rute itu.

Environment variable undefined saat build

$env/static/* membaca nilai saat build. Kalau variabelnya baru ditambahkan setelah deploy terakhir, jalankan redeploy. Untuk nilai yang harus dibaca saat runtime, pakai $env/dynamic/private sebagai gantinya.

Memastikan deploy-nya benar

Tiga pemeriksaan setelah deploy pertama:

1. Lihat mana yang jadi berkas statis. Di dashboard Vercel, buka deploy terakhir lalu tab Source. Halaman yang berhasil di-prerender muncul sebagai .html. Kalau halaman yang kamu kira statis ternyata tidak ada di sana, prerender-nya tidak jalan.
2. Cek header cache. Permintaan kedua ke halaman yang sama harus mengembalikan x-vercel-cache: HIT.
3. Buka log function untuk melihat error runtime yang tidak muncul saat build.

curl -sSI https://app-saya.vercel.app/ | grep -i "x-vercel"

Memperkecil cold start

Halaman yang dilayani serverless function punya jeda kecil saat function-nya baru dibangunkan. Dua hal yang paling berpengaruh:

• Prerender sebanyak mungkin. Halaman statis tidak punya cold start sama sekali karena tidak memanggil function.
• Jaga bundle server tetap ramping. Library besar yang diimpor di +page.server.js ikut dimuat tiap function dibangunkan. Impor hanya bagian yang dipakai, dan pastikan paket yang hanya dibutuhkan saat build ada di devDependencies.

Kamu bisa melihat ukuran keluarannya setelah build:

npm run build
du -sh .svelte-kit/output/server

Batas paket Hobby Vercel

Ringkasan

Untuk Nuxt, langkahnya mirip tapi konfigurasinya berbeda — lihat cara deploy Nuxt ke Vercel. Kalau deploy-mu gagal, cek 15 error deploy paling umum.

Belum yakin Vercel pilihan yang tepat? Lihat Vercel vs Netlify, atau mulai dari panduan lengkap deploy website.