process.env Node.js: Membaca Environment Variable

process.env adalah object dengan satu property untuk setiap environment variable yang diberikan shell ke program Node.js-mu: process.env.PORT, process.env.DATABASE_URL, dan seterusnya. Variabel yang tidak diatur terbaca sebagai undefined, dan variabel yang diatur selalu berupa string. Baca sekali saat startup, beri nilai default, lalu ubah ke tipe yang kamu butuhkan.

// The shell normally sets these: PORT=8080 APP_NAME=shop node index.js
process.env.PORT = '8080';
process.env.APP_NAME = 'shop';

const port = Number(process.env.PORT ?? 3000);
const name = process.env.APP_NAME ?? 'my-app';
const region = process.env.REGION ?? 'eu-west';

console.log(name, 'on port', port, 'in', region);
console.log(typeof process.env.PORT, typeof port);

Hasilnya shop on port 8080 in eu-west (REGION tidak pernah diatur, jadi nilai default-nya yang dipakai), lalu string number: variabelnya berupa teks sampai Number() mengubahnya. Hapus dua baris pengisian pertama lalu jalankan lagi untuk melihat semua nilai default.

Mengatur environment variable di shell

Variabelnya berasal dari tempat Node.js dijalankan. Di terminal:

// macOS and Linux: for one command
PORT=8080 NODE_ENV=production node app.js

// macOS and Linux: for the rest of the terminal session
export PORT=8080

// Windows PowerShell
$env:PORT = "8080"; node app.js

// Windows cmd.exe
set PORT=8080
node app.js

Platform hosting (Heroku, Render, Vercel, Docker, Kubernetes) punya halaman pengaturan atau file untuk hal yang sama; kodemu membacanya dengan cara yang sama.

Semuanya string

Di sinilah sebagian besar bug process.env berasal. 'false' dan '0' adalah string yang tidak kosong, jadi keduanya truthy:

// The shell normally sets this: DEBUG=false node index.js
process.env.DEBUG = 'false';

if (process.env.DEBUG) {
    console.log('naive check: debug is ON');
}

const debug = process.env.DEBUG === 'true';
console.log('correct check: debug is', debug ? 'ON' : 'OFF');

Pengecekan naif mencetak debug is ON untuk variabel yang diisi false, jadi bandingkan dengan string persis yang kamu harapkan. Untuk angka, Number(process.env.X) mengubah nilai yang tidak ada menjadi NaN, jadi pasang nilai default sebelum mengubahnya, seperti yang dilakukan contoh pertama dengan ??.

NODE_ENV

NODE_ENV adalah konvensi, bukan fitur Node.js: Node.js tidak pernah mengaturnya. Library-lah yang membacanya. Express, misalnya, menyembunyikan stack trace dari halaman error saat nilainya production, dan banyak alat melewati pengecekan yang hanya untuk development.

// The shell normally sets this: NODE_ENV=production node index.js
process.env.NODE_ENV = 'production';

const isProduction = process.env.NODE_ENV === 'production';

console.log('mode:', process.env.NODE_ENV);
console.log('verbose logs:', !isProduction);

Hasilnya mode: production dan verbose logs: false; ganti 'production' dengan 'development' dan baris kedua ikut berubah. Pakai saja production, development, dan test, karena library mengecek kata-kata persis itu.

File .env: --env-file dan dotenv

Mengetik setiap variabel sebelum node lama-lama melelahkan. File .env menyimpannya di folder proyekmu, satu per baris:

// .env
PORT=8080
DATABASE_URL=postgres://localhost/shop
API_KEY=dev-key-123

Node.js 20.6 ke atas membacanya dengan sebuah flag, tanpa perlu package:

node --env-file=.env app.js

Di versi yang lebih lama, atau kalau kamu lebih suka, install package dotenv (npm install dotenv) dan muat di bagian paling atas file entry-mu, sebelum ada kode yang membaca process.env:

require('dotenv').config(); // copies .env into process.env

console.log(process.env.PORT); // 8080

Keduanya tidak menimpa variabel yang sudah diatur di shell, jadi pengaturan production menang atas isi file.

Gagal lebih awal saat variabel tidak ada

URL database yang tidak ada seharusnya menghentikan program saat startup dengan pesan yang jelas, bukan membuatnya crash di request pertama sejam kemudian:

// The shell normally sets these
process.env.DATABASE_URL = 'postgres://localhost/shop';

const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter((key) => !process.env[key]);

if (missing.length > 0) {
    console.log('Missing environment variables:', missing.join(', '));
} else {
    console.log('Config OK');
}

Hasilnya Missing environment variables: API_KEY; tambahkan process.env.API_KEY = 'test'; di bagian atas dan hasilnya Config OK. Di program sungguhan, ikuti pesan itu dengan process.exit(1), karena exit code yang bukan nol adalah cara script deploy atau platform container mengetahui bahwa startup gagal.

Jangan pernah commit rahasia

Masukkan .env ke .gitignore di hari kamu membuatnya. Commit .env.example yang berisi nama variabel dan nilai palsu, supaya orang lain tahu apa yang perlu diatur. Key yang pernah di-push ke repository harus dianggap bocor dan diganti, walaupun kamu menghapus commit-nya belakangan.