Setelah proses coding selesai, tahap yang sering dianggap sederhana tetapi sangat penting adalah memastikan aplikasi benar-benar siap dijalankan di lingkungan produksi. Di SvelteKit, dua perintah utama untuk tahap ini adalah npm run build dan npm run preview. Keduanya membantu Anda memverifikasi apakah aplikasi dapat dikompilasi dengan benar dan apakah hasil build berjalan sesuai ekspektasi sebelum benar-benar dideploy ke server atau platform hosting.

Artikel ini cocok sebagai penutup seri dasar SvelteKit karena fokus pada langkah praktis yang hampir selalu dilakukan di akhir pengembangan: membangun project, melakukan preview hasil build, memahami output secara singkat, dan mengecek hal-hal penting sebelum deploy. Selain itu, kita juga akan melihat contoh konfigurasi adapter paling dasar karena proses build SvelteKit sangat bergantung pada adapter yang digunakan.

Mengapa tahap build dan preview penting?

Selama development, Anda biasanya menjalankan aplikasi dengan mode dev server, misalnya melalui npm run dev. Mode ini nyaman untuk pengembangan karena mendukung hot reload, error overlay, dan workflow yang cepat. Namun, mode development bukan representasi penuh dari hasil deploy.

Pada tahap produksi, SvelteKit akan:

  • Melakukan kompilasi aset frontend seperti JavaScript, CSS, dan route terkait.
  • Menyesuaikan output berdasarkan adapter yang digunakan.
  • Mengoptimalkan bundle untuk penggunaan nyata di browser dan/atau server.
  • Menangkap error konfigurasi yang kadang tidak terlihat saat mode development.

Karena itu, menjalankan build dan preview membantu menjawab pertanyaan penting berikut:

  • Apakah seluruh route bisa dibangun tanpa error?
  • Apakah import, dependency, dan file konfigurasi sudah benar?
  • Apakah environment variable yang dibutuhkan sudah tersedia?
  • Apakah hasil produksi tetap bekerja seperti saat development?

Catatan: Banyak masalah deploy sebenarnya bisa ditemukan lebih awal hanya dengan rutin menjalankan npm run build dan npm run preview sebelum mendorong kode ke server atau layanan hosting.

Memastikan adapter SvelteKit sudah benar

Sebelum build dijalankan, hal pertama yang perlu dicek adalah adapter. SvelteKit tidak menghasilkan output deploy yang sama untuk semua target. Output build ditentukan oleh adapter, misalnya untuk Node.js server, static hosting, atau platform tertentu seperti Vercel dan Netlify.

Untuk contoh paling dasar dan mudah dipahami, kita bisa menggunakan @sveltejs/adapter-auto atau @sveltejs/adapter-node, tergantung kebutuhan.

Opsi 1: adapter-auto untuk tahap awal

Jika Anda masih berada di tahap belajar atau belum menentukan target hosting final, adapter-auto sering menjadi pilihan paling sederhana. Adapter ini mencoba menyesuaikan dengan environment deployment yang didukung.

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

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

export default config;

Konfigurasi di atas biasanya cukup untuk project dasar. Namun, untuk deployment yang lebih terprediksi, adapter spesifik sering lebih disarankan.

Opsi 2: adapter-node untuk server Node.js

Jika Anda ingin menjalankan hasil build di server Node.js sendiri, gunakan @sveltejs/adapter-node. Ini cocok untuk VPS, container Docker, atau server backend yang Anda kontrol langsung.

npm install -D @sveltejs/adapter-node
import adapter from '@sveltejs/adapter-node';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

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

export default config;

Kapan memilih yang mana?

  • adapter-auto: baik untuk project awal atau saat target hosting belum final.
  • adapter-node: pilih jika Anda tahu aplikasi akan dijalankan sebagai server Node.js.

Trade-off-nya, adapter-auto praktis tetapi kadang kurang eksplisit. Untuk produksi, adapter yang jelas biasanya membuat proses build dan deploy lebih mudah dipahami serta lebih konsisten.

Menjalankan npm run build

Setelah adapter siap, jalankan perintah build dari root project:

npm run build

Perintah ini akan menjalankan proses build produksi. SvelteKit akan memanggil tooling di bawahnya, umumnya Vite, untuk membangun aset aplikasi dan menghasilkan output sesuai adapter.

Apa yang terjadi saat build?

Secara umum, proses ini akan:

  • Memeriksa dan membundel modul yang digunakan aplikasi.
  • Menghasilkan aset teroptimasi untuk frontend.
  • Membuat output server atau static files tergantung adapter.
  • Menampilkan error bila ada route, import, atau konfigurasi yang bermasalah.

Contoh output di terminal bisa berbeda-beda, tetapi biasanya Anda akan melihat ringkasan seperti:

  • File yang berhasil dibangun.
  • Ukuran bundle atau aset.
  • Direktori output hasil build.
  • Status sukses atau gagal.

Anda tidak perlu menghafal seluruh output terminal. Yang penting adalah memahami tanda-tanda berikut:

  • Build sukses: proses selesai tanpa error.
  • Build gagal: ada stack trace atau pesan error yang harus diperbaiki sebelum deploy.
  • Peringatan ukuran bundle: tidak selalu fatal, tetapi perlu diperhatikan jika aplikasi mulai berat.

Masalah umum saat build

Beberapa error baru muncul saat build produksi, walaupun saat npm run dev aplikasi tampak berjalan normal. Contoh masalah yang cukup sering terjadi:

  • Mengakses API browser seperti window atau document di konteks server.
  • Environment variable yang belum tersedia.
  • Import path salah huruf besar-kecilnya, terutama saat deploy ke Linux.
  • Dependency belum terpasang atau dipasang di kategori yang salah.
  • Konfigurasi adapter tidak sesuai target deployment.

Jika build gagal, baca error dari baris paling relevan, biasanya file dan nomor baris akan ditampilkan. Hindari langsung menebak-nebak tanpa membaca pesan error inti.

Menjalankan npm run preview

Jika build berhasil, langkah berikutnya adalah menjalankan preview:

npm run preview

Perintah ini akan menjalankan hasil build secara lokal dalam mode yang lebih mendekati produksi. Dengan kata lain, Anda tidak lagi melihat aplikasi dari dev server, tetapi dari output build yang sudah dihasilkan sebelumnya.

Kenapa preview penting?

npm run preview membantu Anda memverifikasi bahwa hasil produksi benar-benar bisa dijalankan. Ini penting karena perilaku di mode development dan mode produksi tidak selalu identik. Preview memungkinkan Anda mengecek:

  • Apakah navigasi antarroute tetap berjalan baik.
  • Apakah halaman dinamis tetap memuat data dengan benar.
  • Apakah asset static berhasil dimuat.
  • Apakah tidak ada error runtime yang hanya muncul setelah build.

Biasanya terminal akan menampilkan URL lokal, misalnya http://localhost:4173 atau port lain tergantung konfigurasi dan ketersediaan port. Buka alamat tersebut di browser lalu uji alur utama aplikasi.

Apa yang perlu diuji saat preview?

  1. Buka halaman utama dan pastikan tidak ada error di browser console.
  2. Cek route penting seperti halaman detail, form, login, atau dashboard.
  3. Pastikan data dari endpoint internal atau API eksternal tetap termuat.
  4. Periksa file statis seperti gambar, favicon, dan stylesheet.
  5. Uji halaman error atau route yang tidak ditemukan jika aplikasi memilikinya.

Jika project menggunakan rendering di server, pastikan juga halaman tetap berfungsi saat di-refresh langsung, bukan hanya saat navigasi dari dalam aplikasi.

Checklist sebelum deploy

Sebelum menganggap project siap deploy, lakukan pemeriksaan sederhana tetapi penting berikut ini:

1. Pastikan build bersih tanpa error

Jangan deploy project yang masih gagal di npm run build. Ini terdengar jelas, tetapi dalam praktiknya kadang ada kebiasaan “nanti diperbaiki di server”. Sebaiknya hindari pola seperti itu karena masalah di server biasanya lebih sulit dilacak.

2. Cek adapter sesuai target hosting

Jika target deploy adalah Node server, gunakan adapter Node. Jika targetnya static hosting, gunakan adapter yang sesuai untuk output statis. Salah adapter bisa membuat hasil build tidak cocok dengan platform deployment.

3. Verifikasi environment variable

Pastikan semua variabel environment yang dipakai aplikasi tersedia di lingkungan produksi. Bedakan nilai untuk development dan production bila perlu. Jangan menyimpan secret langsung di source code.

4. Periksa penggunaan API browser

Dalam SvelteKit, sebagian kode bisa berjalan di server. Jika Anda mengakses window, document, atau localStorage tanpa pengamanan, build atau runtime produksi bisa bermasalah. Gunakan pendekatan yang aman sesuai konteks eksekusi.

5. Uji route utama dan skenario penting

Minimal uji alur yang paling kritis bagi pengguna, misalnya membuka homepage, login, submit form, dan melihat halaman data. Tujuannya bukan menggantikan testing otomatis, tetapi memastikan tidak ada kerusakan yang sangat jelas menjelang deploy.

6. Cek asset dan path

Pastikan semua gambar, icon, dan file statis termuat benar. Jika aplikasi akan di-deploy pada subpath tertentu, periksa kembali konfigurasi path agar asset tidak 404.

7. Review dependency produksi

Pastikan dependency yang dibutuhkan saat runtime tersedia. Kadang package dipasang hanya sebagai devDependency padahal dibutuhkan saat aplikasi berjalan di server produksi.

Tips debugging jika build atau preview bermasalah

Baca error pertama yang relevan

Jangan terpaku pada puluhan baris output. Sering kali akar masalah ada di pesan error pertama yang menyebut file dan baris tertentu.

Bandingkan perilaku dev dan preview

Jika aplikasi berjalan saat npm run dev tetapi rusak saat npm run preview, kemungkinan besar masalahnya berkaitan dengan perbedaan mode development vs produksi, SSR, atau konfigurasi adapter.

Periksa log browser dan terminal

Error di preview bisa muncul di dua tempat: terminal dan browser console. Periksa keduanya. Error frontend belum tentu muncul di terminal, dan error server belum tentu terlihat jelas di browser.

Gunakan perubahan kecil dan bertahap

Jika setelah perubahan tertentu build mulai gagal, telusuri commit atau perubahan terakhir. Pendekatan ini jauh lebih efektif daripada mengubah banyak hal sekaligus.

Penutup

Build dan preview adalah langkah akhir yang wajib dilakukan sebelum deploy aplikasi SvelteKit dari project lokal. Dengan menjalankan npm run build, Anda memastikan aplikasi benar-benar bisa dikompilasi untuk produksi. Dengan npm run preview, Anda memeriksa hasil build secara lokal agar lebih mirip kondisi nyata setelah deploy.

Untuk project dasar, proses ini tidak rumit, tetapi sangat bernilai. Pastikan adapter sudah sesuai, pahami output build secara garis besar, lalu lakukan pengecekan singkat terhadap route, asset, environment variable, dan potensi error runtime. Dengan kebiasaan ini, Anda bisa mengurangi kejutan saat deploy dan membuat transisi dari development ke production menjadi jauh lebih mulus.

Jika artikel ini menjadi penutup seri dasar SvelteKit Anda, maka takeaway utamanya sederhana: jangan berhenti di “aplikasi jalan di localhost dev server”. Pastikan juga aplikasi lolos build dan preview, karena itulah bentuk paling dekat dengan kondisi deploy yang sebenarnya.