Panduan Konfigurasi Versi Node.js Mandiri untuk Setiap Proyek dengan ServBay (macOS)

ServBay adalah lingkungan pengembangan web lokal yang powerful dan dirancang khusus untuk developer. Platform ini memberikan solusi all-in-one dengan integrasi berbagai bahasa pemrograman, database, dan server web, termasuk Node.js. Salah satu keunggulan utama ServBay adalah dukungan asli untuk banyak versi Node.js dan kemudahan pengelolaan versinya. Melalui file konfigurasi sederhana, Anda dapat dengan mudah menentukan versi Node.js yang diperlukan setiap proyek, tanpa harus bergantung pada manajer versi eksternal seperti NVM, FNM, atau Docker. Ini menyederhanakan workflow Anda, mencegah polusi lingkungan global, dan menghindari konflik versi.

Dokumen ini akan membahas secara detail bagaimana memanfaatkan file .servbay.config ServBay untuk kontrol versi Node.js di level proyek.

Mengapa Menggunakan .servbay.config ServBay untuk Manajemen Versi Node.js?

Metode manajemen versi Node.js tradisional seperti NVM atau instalasi manual kerap membawa kesulitan tertentu:

• Polusi & Konflik Global: Instalasi global atau penggantian versi secara global dapat menyebabkan konflik dependensi antar proyek.
• Instalasi & Kompilasi Lama: Instal atau ganti arsitektur (misal x86_64 dan arm64) kerap membutuhkan kompilasi ulang modul yang memakan waktu dan merepotkan.
• Overhead Docker: Untuk sekadar butuh versi Node.js tertentu, penggunaan container Docker cenderung terlalu berat.

ServBay hadir dengan solusi lebih elegan dengan pra-instalasi berbagai versi utama Node.js (saat ini mendukung semua versi mayor dan minor dari v12 sampai v23; Anda bisa mengelolanya lewat bagian “Packages” di aplikasi ServBay). Bersama file .servbay.config, inilah kelebihannya:

• Beralih Instan: Versi telah terinstall, peralihan nyaris seketika.
• Isolasi Proyek: Pengaturan hanya berlaku di direktori proyek, memungkinkan isolasi versi secara nyata.
• Tanpa Polusi Global: Sistem Anda tetap bersih, tidak mengubah environment global.
• Terintegrasi dengan ServBay: Terhubung seutuhnya dengan ekosistem ServBay, dapat digunakan bersama paket lain seperti PHP, database, server web, dan lainnya.

Prasyarat

Sebelum memulai, pastikan:

1. ServBay telah terinstal dan berjalan dengan baik di macOS Anda.
2. Di aplikasi ServBay, pada daftar “Packages”, Anda telah mengaktifkan versi Node.js yang diperlukan proyek Anda.
3. Anda memiliki direktori proyek yang ingin diatur ke versi Node.js tertentu.

Prinsip Kerja

Ketika bekerja di terminal terintegrasi ServBay, platform akan memonitor posisi direktori Anda. Setiap kali Anda berpindah ke sebuah direktori (cd), ServBay akan mencari file bernama .servbay.config di direktori itu maupun di seluruh parent-nya. Begitu ditemukan (mengutamakan file terdekat), ServBay akan membaca dan memproses pengaturan di dalamnya, lalu melakukan penyesuaian environment session terminal Anda, misalnya dengan mengubah variabel PATH agar mengarah ke folder instalasi Node.js sesuai pengaturan di file .servbay.config.

Mekanisme ini memastikan setiap sesi terminal di direktori proyek yang berbeda, dapat otomatis memuat serta memakai versi Node.js sesuai per proyek — tanpa perlu beralih manual.

Langkah-langkah Konfigurasi

Mengatur versi Node.js independen proyek sangat mudah, hanya dua langkah:

Langkah 1: Membuat & Mengedit File .servbay.config

Pada root direktori proyek Anda (biasanya yang berisi package.json), buat file baru bernama .servbay.config.

Buka dengan editor teks favorit, lalu tambahkan isi berikut:

# Tentukan versi mayor Node.js yang digunakan proyek
# ServBay akan otomatis memilih versi terbaru yang telah terinstal dari mayor ini
NODE_VERSION=20

# Opsional: Konfigurasi mirror npm atau pnpm untuk mempercepat instalasi dependencies
# Jika Anda di Tiongkok daratan, disarankan gunakan mirror lokal
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# Opsional: Tentukan direktori cache npm/pnpm
# Disarankan meletakkan cache di direktori tmp ServBay untuk mencegah polusi atau konsumsi ruang sistem
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

Penjelasan Pengaturan:

• NODE_VERSION: Wajib. Versi mayor Node.js yang dibutuhkan proyek. Misal, 20 berarti ServBay akan memakai Node.js 20.x.x terbaru pada proyek. Pastikan versi tersebut telah diinstal via ServBay.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: Opsional. Mirror repository untuk Yarn atau npm; sangat berguna untuk mempercepat instalasi dependency, terutama jika terkendala jaringan.
• NPM_CONFIG_CACHE: Opsional. Tentukan folder cache npm/pnpm. Pengaturan di direktori sementara ServBay (/Applications/ServBay/tmp/npm/cache) membantu memusatkan cache sehingga file tidak tersebar sembarangan.

Simpan dan tutup file .servbay.config.

Langkah 2: Verifikasi Versi di Terminal ServBay

1. Buka aplikasi utama ServBay.

2. Klik tombol “Terminal” untuk membuka terminal terintegrasi.

3. Gunakan perintah cd untuk masuk ke folder proyek Anda.

   cd /Applications/ServBay/www/your-project-name

   (Ganti /Applications/ServBay/www/your-project-name dengan path proyek sebenarnya)

4. Jalankan node -v untuk memeriksa versi aktif Node.js.

   node -v

   Output harus menunjukkan versi Node.js seperti yang Anda tetapkan pada .servbay.config (contoh: v20.x.x).

5. Anda juga bisa menjalankan npm -v, pnpm -v, atau yarn -v untuk mengecek apakah package manager sudah sesuai dan terhubung dengan versi Node.js yang dipilih.

Kini, setiap kali Anda menjalankan perintah Node.js, npm, pnpm, atau yarn di folder proyek tersebut, versi yang digunakan akan selalu sesuai dengan yang diatur dalam .servbay.config.

Contoh Praktik

Berikut contoh sederhana penggunaan .servbay.config untuk otomatis berganti versi Node.js di dua proyek berbeda.

Misal, Anda memiliki dua proyek: project-a butuh Node.js v18 dan project-b butuh Node.js v20.

1. Buat direktori proyek & file konfigurasi:

   # Membuat direktori sample project di folder www ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # Untuk project-a, buat .servbay.config dengan Node.js v18
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # Untuk project-b, buat .servbay.config dengan Node.js v20
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. Verifikasi switching di terminal ServBay:

   Buka terminal ServBay dan jalankan:

   # Masuk ke folder project-a
   cd /Applications/ServBay/www/project-a
   # Cek versi Node.js
   node -v
   # Output: v18.x.x
   
   # Masuk ke project-b
   cd ../project-b
   # Cek versi Node.js
   node -v
   # Output: v20.x.x
   
   # Kembali ke project-a
   cd ../project-a
   # Cek versi Node.js
   node -v
   # Output: v18.x.x

Dari contoh di atas, Anda bisa melihat bahwa ServBay secara otomatis meload Pengaturan NODE_VERSION yang sesuai dari .servbay.config sesuai lokasi direktori Anda, memungkinkan switching versi Node.js yang seamless.

Gambar berikut menampilkan bagaimana switching versi Node.js berjalan otomatis sesuai .servbay.config ketika berpindah antar direktori proyek (ilustrasi, tampilan aktual bisa berbeda):

Catatan Penting

• File .servbay.config harus ditempatkan di direktori proyek atau salah satu parent-nya. ServBay akan mencari dari direktori saat ini ke atas, dan memakai file pertama yang ditemukan (yang terdekat dengan posisi Anda).
• Pastikan Anda bekerja pada terminal bawaan ServBay, atau pastikan environment variabel ServBay sudah dimuat jika menggunakan terminal eksternal.
• Versi pada NODE_VERSION harus sudah diinstal dan diaktifkan lewat aplikasi ServBay. Jika belum diinstal, ServBay mungkin akan fallback ke versi default, atau gagal menjalankan perintah Node.js.
• Pengaturan di .servbay.config hanya memengaruhi session terminal dan proses turunannya, tidak akan mengubah sistem global atau proses di luar lingkungan ServBay.

Tanya Jawab Umum (FAQ)

T: Apa yang terjadi jika direktori proyek saya tidak memiliki file .servbay.config?

J: Jika ServBay tidak menemukan .servbay.config di direktori sekarang maupun di parent-nya, maka akan digunakan pengaturan global/default (biasanya yang ditandai “default” di aplikasi ServBay).

T: Bagaimana cara melihat daftar versi Node.js yang tersedia di ServBay?

J: Buka aplikasi ServBay, navigasi ke menu “Packages” di sisi kiri. Di sana Anda dapat melihat seluruh paket (termasuk Node.js berbagai versi), mengaktifkan, atau menonaktifkan versi tertentu.

T: Apakah konfigurasi di .servbay.config akan memengaruhi seluruh sistem saya?

J: Tidak. Pengaturan tersebut hanya berlaku sementara, khusus untuk sesi terminal ServBay atau proses yang dijalankan dengan environment ServBay. Sistem global Anda tidak akan terpengaruh maupun program lain di luar ServBay. Inilah kunci utama isolasi proyek di ServBay.

T: Selain NODE_VERSION, adakah pengaturan lain di .servbay.config yang berkaitan dengan ServBay?

J: Ya, file .servbay.config adalah mekanisme pengaturan environment variables di level proyek. Selain Node.js, Anda dapat menetapkan variabel lingkungan lain sesuai kebutuhan, yang hanya berlaku ketika menjalankan perintah di folder itu. Dukungan pengaturan spesifik akan bertambah seiring update ServBay, namun pada dasarnya fungsinya sebagai pemuat environment variables utama.

Kesimpulan

Dengan memanfaatkan file .servbay.config, Anda bisa dengan mudah dan efisien menentukan serta mengelola versi Node.js terpisah untuk setiap proyek lokal Anda. Cara ini lebih ringan dan praktis dibanding manajer versi tradisional maupun containerization, dan sangat menyatu dengan ekosistem ServBay — membantu workflow Anda menjadi stabil dan kolaboratif. Segera terapkan .servbay.config di proyek Anda dan rasakan kemudahan luar biasa dari ServBay!