Environment variable adalah salah satu cara paling umum untuk menyimpan konfigurasi aplikasi tanpa menuliskannya langsung di dalam source code. Dalam pengembangan aplikasi modern, pendekatan ini sangat penting karena membantu memisahkan kode dari konfigurasi. Saat Anda menggunakan Bun sebagai runtime JavaScript, membaca environment variable juga sangat sederhana dan mirip dengan ekosistem Node.js.

Artikel ini membahas dasar penggunaan environment variable di Bun, alasan mengapa teknik ini penting, cara membaca nilainya, serta contoh kecil yang bisa langsung dipakai. Fokusnya adalah praktik yang sederhana tetapi tetap mengikuti kebiasaan yang baik dalam pengembangan aplikasi.

Mengapa Environment Variable Penting?

Konfigurasi aplikasi sering berubah tergantung lingkungan tempat aplikasi dijalankan. Misalnya:

  • PORT bisa berbeda antara mesin lokal dan server produksi.
  • APP_NAME mungkin dipakai untuk menampilkan nama layanan atau identitas aplikasi.
  • DATABASE_URL, token API, atau secret key tidak seharusnya ditanam langsung ke source code.

Dengan environment variable, Anda tidak perlu mengubah file kode setiap kali berpindah lingkungan. Ini memberi beberapa keuntungan praktis:

  • Lebih aman karena data sensitif tidak disimpan langsung di file JavaScript/TypeScript.
  • Lebih fleksibel karena nilai bisa diubah tanpa mengedit kode.
  • Lebih mudah dideploy karena konfigurasi bisa diberikan dari shell, container, CI/CD, atau platform hosting.
  • Lebih rapi karena kode fokus pada logika aplikasi, bukan detail konfigurasi.

Prinsip ini umum dipakai di aplikasi backend, CLI tool, service internal, dan juga banyak sistem berbasis container seperti Docker dan Kubernetes.

Cara Bun Membaca Environment Variable

Di Bun, cara paling umum untuk membaca environment variable adalah melalui process.env. Ini akan terasa familiar jika Anda pernah menggunakan Node.js. Nilai environment variable biasanya tersedia sebagai string, atau undefined jika tidak ada.

Contoh sederhana:

console.log(process.env.PORT);
console.log(process.env.APP_NAME);

Jika Anda menjalankan program dengan environment variable yang sudah diset, Bun akan membaca nilainya dari sana. Misalnya di shell Unix-like:

PORT=3000 APP_NAME=my-bun-app bun run index.ts

Jika file index.ts berisi:

console.log("PORT:", process.env.PORT);
console.log("APP_NAME:", process.env.APP_NAME);

Maka hasilnya akan menampilkan nilai yang diberikan saat proses dijalankan.

Hal penting yang perlu diingat: isi process.env umumnya berbentuk string. Jadi jika Anda ingin menggunakan PORT sebagai angka, Anda perlu mengubahnya secara eksplisit.

const port = Number(process.env.PORT || 3000);
console.log(port);

Pendekatan ini bekerja karena jika process.env.PORT tidak ada, aplikasi memakai nilai bawaan 3000. Ini adalah pola yang sangat umum untuk konfigurasi sederhana.

Contoh Proyek Sederhana

1. Membuat file aplikasi

Misalkan Anda memiliki file app.ts seperti berikut:

const appName = process.env.APP_NAME || "Aplikasi Bun";
const port = Number(process.env.PORT || 3000);

console.log(`Menjalankan ${appName} di port ${port}`);

Kode di atas melakukan dua hal penting:

  • Membaca APP_NAME dan memberi nilai default jika belum disediakan.
  • Membaca PORT, lalu mengubahnya dari string menjadi number.

Jika dijalankan tanpa environment variable:

bun run app.ts

Output:

Menjalankan Aplikasi Bun di port 3000

Jika dijalankan dengan environment variable:

APP_NAME="Server Internal" PORT=8080 bun run app.ts

Output:

Menjalankan Server Internal di port 8080

Contoh ini kecil, tetapi mencerminkan pola konfigurasi yang dipakai di aplikasi nyata.

2. Menggunakannya pada server HTTP sederhana

Supaya lebih praktis, mari gunakan konfigurasi tersebut dalam server Bun:

const appName = process.env.APP_NAME || "Bun App";
const port = Number(process.env.PORT || 3000);

Bun.serve({
  port,
  fetch() {
    return new Response(`${appName} berjalan di port ${port}`);
  },
});

console.log(`${appName} aktif di http://localhost:${port}`);

Di sini, environment variable dipakai untuk mengontrol perilaku aplikasi saat runtime. Anda tidak perlu mengubah source code hanya untuk mengganti port atau nama aplikasi. Ini sangat membantu saat aplikasi dipindahkan dari lokal ke staging atau produksi.

Menggunakan File .env

Dalam banyak proyek, environment variable tidak selalu diberikan langsung lewat command line. Untuk pengembangan lokal, pendekatan yang lazim adalah menyimpan konfigurasi ke file .env. Bun mendukung pola ini sehingga Anda bisa menyiapkan nilai konfigurasi lebih praktis saat development.

Contoh file .env:

APP_NAME=Belajar Bun
PORT=4000

Lalu pada file aplikasi:

const appName = process.env.APP_NAME || "Default App";
const port = Number(process.env.PORT || 3000);

console.log(`Nama aplikasi: ${appName}`);
console.log(`Port: ${port}`);

Saat dijalankan, Bun dapat membaca nilai dari file lingkungan tersebut sehingga Anda tidak perlu menulis ulang variabel di terminal setiap kali.

Manfaat file .env antara lain:

  • Mempermudah pengembangan lokal.
  • Konfigurasi lebih konsisten untuk seluruh anggota tim.
  • Mengurangi kesalahan karena lupa mengekspor variabel di shell.

Namun, file .env juga perlu dikelola dengan benar. Untuk data sensitif, praktik umum adalah menambahkan file ini ke .gitignore agar tidak ikut masuk ke repository publik atau internal yang tidak semestinya.

Catatan penting: jangan menyimpan secret seperti API key, password database, atau token akses langsung di source code. Simpan di environment variable atau mekanisme secret management yang sesuai dengan lingkungan deployment Anda.

Praktik yang Disarankan

1. Selalu sediakan nilai default untuk konfigurasi non-kritis

Untuk nilai seperti PORT atau nama aplikasi, menyediakan default akan membuat aplikasi lebih mudah dijalankan di lokal.

const port = Number(process.env.PORT || 3000);

Ini mengurangi friction saat development dan membuat perilaku aplikasi lebih dapat diprediksi.

2. Validasi variabel yang wajib ada

Tidak semua environment variable boleh opsional. Misalnya jika aplikasi harus memiliki DATABASE_URL, Anda sebaiknya memeriksa keberadaannya saat startup.

const databaseUrl = process.env.DATABASE_URL;

if (!databaseUrl) {
  throw new Error("DATABASE_URL harus diset sebelum aplikasi dijalankan");
}

Dengan validasi di awal, kesalahan akan muncul lebih cepat dan lebih jelas dibanding menunggu aplikasi gagal di tengah proses.

3. Perhatikan tipe data

Nilai dari process.env biasanya berupa string. Ini berarti Anda perlu melakukan parsing jika ingin memakai number atau boolean.

const port = Number(process.env.PORT || 3000);
const isProduction = process.env.NODE_ENV === "production";

Kesalahan umum adalah menganggap process.env.PORT sudah bertipe number, padahal tidak.

4. Pusatkan pembacaan konfigurasi

Untuk aplikasi yang mulai berkembang, sebaiknya pembacaan environment variable dikumpulkan di satu file khusus, misalnya config.ts.

export const config = {
  appName: process.env.APP_NAME || "Bun App",
  port: Number(process.env.PORT || 3000),
};

Lalu dipakai di tempat lain:

import { config } from "./config";

console.log(config.appName);
console.log(config.port);

Pendekatan ini mempermudah perawatan, validasi, dan pengujian aplikasi karena konfigurasi tidak tersebar di banyak file.

Kesalahan yang Sering Terjadi

String tidak diubah ke tipe yang dibutuhkan

Contoh paling sering adalah port. Jika Anda membaca process.env.PORT tanpa parsing, Anda mungkin tetap mendapat string. Pada beberapa kasus ini masih terlihat bekerja, tetapi bisa menimbulkan bug saat nilai dipakai dalam operasi numerik.

Nama variabel tidak konsisten

Misalnya di file .env Anda menulis APPNAME, tetapi di kode membaca APP_NAME. Hasilnya akan undefined. Karena itu, gunakan penamaan yang konsisten dan mudah dibaca.

Mengandalkan environment variable tanpa fallback

Untuk development lokal, tidak adanya fallback bisa membuat pengalaman menjalankan aplikasi jadi kurang nyaman. Sebaliknya, untuk nilai yang wajib seperti secret penting, justru jangan berikan fallback yang diam-diam berbahaya. Bedakan mana yang opsional dan mana yang wajib.

Secret ikut ter-commit ke repository

Ini adalah masalah keamanan yang cukup sering terjadi. Jika Anda memakai file .env, pastikan file tersebut masuk ke .gitignore bila berisi data sensitif.

.env

Jika tim Anda membutuhkan contoh konfigurasi, buat file terpisah seperti .env.example yang hanya berisi nama variabel tanpa nilai rahasia.

APP_NAME=
PORT=
DATABASE_URL=

Tips Debugging

Jika environment variable terasa tidak terbaca, periksa beberapa hal berikut:

  • Pastikan nama variabel sama persis antara yang diset dan yang dibaca.
  • Pastikan proses dijalankan di lingkungan yang benar.
  • Jika memakai file .env, cek apakah file berada di lokasi yang sesuai dan formatnya benar.
  • Tambahkan log sementara untuk memeriksa nilai yang masuk, tetapi hindari mencetak secret ke terminal atau log produksi.

Contoh debug sederhana:

console.log({
  APP_NAME: process.env.APP_NAME,
  PORT: process.env.PORT,
});

Untuk variabel sensitif, cukup cek keberadaannya tanpa mencetak isi lengkapnya.

console.log("DATABASE_URL tersedia:", Boolean(process.env.DATABASE_URL));

Pendekatan ini membantu Anda memastikan konfigurasi sudah terbaca tanpa membocorkan data penting.

Penutup

Membaca environment variable di Bun adalah langkah dasar yang sangat penting untuk membangun aplikasi yang rapi, fleksibel, dan lebih aman. Dalam praktik sehari-hari, Anda bisa menggunakan process.env untuk mengambil nilai konfigurasi seperti PORT dan APP_NAME, lalu memberikan default atau validasi sesuai kebutuhan.

Untuk proyek kecil, pola ini sangat cukup. Untuk aplikasi yang lebih besar, sebaiknya konfigurasi dipusatkan dalam satu modul dan divalidasi sejak awal saat aplikasi start. Yang paling penting, hindari menaruh secret langsung di source code. Simpan konfigurasi sensitif di environment variable atau sistem manajemen secret yang sesuai dengan infrastruktur Anda.

Dengan memahami pola dasar ini sejak awal, Anda akan lebih mudah mengembangkan aplikasi Bun yang siap berjalan di berbagai lingkungan, mulai dari lokal hingga produksi.