File .env Dijelaskan: Parsing, Konversi JSON & Konfigurasi

File .env adalah daftar pasangan KEY=VALUE dalam teks polos yang menjaga konfigurasi dan rahasia (secret) tetap berada di luar kode sumber Anda. Inilah format yang dimuat Node, Vite, Next.js, Python, Ruby, dan Docker Compose ke dalam environment proses. Jika Anda sedang mencari env to json, biasanya Anda menginginkan salah satu dari dua hal: mengubah .env menjadi JSON terstruktur untuk perkakas (tooling), atau memahami aturannya dengan cukup baik agar bisa melakukannya dengan aman.

Ada tiga hal yang sering membingungkan banyak orang, jadi mari kita selesaikan dulu:

1. File .env itu datar (flat). Tidak ada penyusunan bertingkat (nesting). Setiap kunci (key) berada di level paling atas.
2. Setiap nilai (value) adalah string. dotenv tidak pernah memaksakan tipe (type coercion). PORT=8080 dimuat sebagai "8080", bukan 8080.
3. Tata bahasanya informal. Tidak ada spesifikasi formal, sehingga para loader berbeda pendapat di sisi-sisi pelik, yaitu soal kutip, komentar, dan escape.

Panduan ini membahas aturan parsing dotenv, pemetaan .env↔JSON (dan mengapa Anda perlu mengonversi ke salah satu arah), matriks keputusan untuk memilih .env atau JSON, serta cara memvalidasi konfigurasi Anda sebelum dirilis. Semua yang dijelaskan di sini berjalan di Konverter ENV ke JSON sepenuhnya di dalam browser Anda, sehingga .env yang penuh kredensial asli sekalipun tidak pernah meninggalkan halaman.

Apa itu file .env?

File .env adalah standar de facto untuk konfigurasi environment. Pustaka dotenv, beserta port-nya ke hampir setiap bahasa, membaca file tersebut dan menyuntikkan setiap pasangan ke dalam proses yang sedang berjalan. Aplikasi Anda lalu membaca process.env.DATABASE_URL alih-alih menanamkan string koneksi secara langsung di kode. Karena file ini menyimpan kata sandi basis data, kunci API, secret OAuth, dan token akses, file ini hampir selalu di-git-ignore dan diperlakukan sebagai data sensitif.

Anatomi sebuah baris

Setiap baris yang bermakna adalah pasangan KEY=VALUE, dipisah pada tanda = pertama. Baris komentar dan baris kosong dilewati, dan awalan export yang opsional dibuang:

# Database — this whole line is a comment
DATABASE_URL=postgres://user:pass@localhost:5432/mydb
DATABASE_POOL_SIZE=10

# A blank line above is ignored
export DEPLOY_ENV=production   # the `export` prefix is removed
JWT_SECRET="super secret value"

Kunci adalah segala sesuatu sebelum tanda = pertama, dipangkas dari spasi di sekitarnya. Awalan export ada agar file bisa langsung di-source di dalam shell; loader dotenv membuangnya secara otomatis. Pemisahan pada tanda = pertama itu penting karena nilai seperti DATABASE_URL sering kali mengandung karakter = tersendiri di dalam query string.

Mengapa konfigurasi hidup di dalam environment

Alasannya berasal dari Twelve-Factor App, yang menganjurkan agar konfigurasi disimpan di dalam environment. Konfigurasi berubah per deploy (dev, staging, production), sementara kodenya tetap sama. Menyimpannya di environment berarti Anda bisa mengganti host basis data tanpa menyunting atau men-deploy ulang kode sumber, dan build yang sama berjalan di mana saja.

Satu kesalahpahaman yang umum: orang mengutip “konfigurasi tidak boleh ada di file” lalu menyimpulkan bahwa .env itu terlarang. Aturan yang sebenarnya lebih sempit. Konfigurasi tidak boleh berupa file yang di-commit di dalam aplikasi, bercampur dengan kode dan dilacak dalam version control. File .env lokal yang di-git-ignore untuk pengembangan itu wajar dan standar. Yang harus Anda hindari adalah mengirim .env asli ke production dengan secret tertanam di dalamnya.

Aturan parsing .env (kasus pelik yang membuat perkakas berbeda pendapat)

Karena tidak ada spesifikasi formal untuk parse a .env file, setiap loader membuat keputusannya sendiri di area perbatasan. Aturan di bawah ini adalah konvensi dotenv yang dianut secara luas, yang diimplementasikan oleh konverter dan disepakati oleh sebagian besar runtime.

Kutip dan escape

Cara sebuah nilai dikutip mengubah segalanya:

• Kutip ganda (double quotes) memproses urutan escape (escape sequence). \n menjadi baris baru, \t menjadi tab, \r menjadi carriage return, \\ menjadi backslash, dan \" menjadi kutip ganda harfiah. Nilai berkutip ganda juga bisa membentang ke beberapa baris sampai kutip penutup, dan begitulah kunci privat PEM bisa muat di dalam .env.
• Kutip tunggal (single quotes) bersifat harfiah. Tidak ada pemrosesan escape, persis seperti di shell. 'no \n escapes here' mempertahankan backslash dan huruf n apa adanya.
• Tanpa kutip (unquoted) berlaku sampai akhir baris, dengan spasi di belakang dipangkas. Tanda # sebaris (spasi diikuti pagar) memulai komentar yang akan dibuang.

Aturan terakhir itulah yang sering menjegal orang saat memakai warna heksadesimal. COLOR=#ff0000 kehilangan semua yang ada setelah #. Kutiplah (COLOR="#ff0000") dan nilainya akan selamat.

Semuanya adalah string

Inilah fakta paling penting tentang dotenv format. PORT=8080 tidak dimuat sebagai angka 8080. Ia dimuat sebagai string "8080", karena nilai process.env selalu berupa string saat runtime. dotenv tidak pernah memaksakan tipe.

Hal ini menimbulkan bug yang nyata. if (process.env.DEBUG) bernilai truthy bahkan ketika DEBUG=false, karena "false" adalah string yang tidak kosong. Perbandingan numerik gagal secara diam-diam karena "8080" bukanlah 8080. Fitur “infer types” apa pun, termasuk tombol di konverter, adalah lapisan kenyamanan yang ditambahkan di atas dotenv, bukan bagian dari standar. Gunakan dengan sengaja, dengan kesadaran bahwa JSON-nya akan berbeda dari apa yang sebenarnya diterima aplikasi Anda.

Kunci ganda, nilai multi-baris, dan interpolasi

Ketika kunci yang sama muncul dua kali, kemunculan terakhir yang menang. Nilai yang lebih awal dibuang secara diam-diam. Ini adalah jebakan miskonfigurasi yang sering terjadi: sebuah duplikat yang nyasar di dekat bagian bawah file yang panjang diam-diam menutupi nilai yang sebenarnya ingin Anda pakai. Konverter yang baik akan menandai duplikat dengan peringatan alih-alih menelannya begitu saja.

Nilai multi-baris hanya berfungsi di dalam kutip ganda, membungkus melintasi beberapa baris sampai tanda " penutup. Dan interpolasi ${VAR}, yang mereferensikan satu variabel dari variabel lain, ada di sebagian loader tetapi tidak universal. Jangan mengandalkannya lintas runtime; file yang interpolasinya berjalan baik di satu stack bisa saja memuat string ${VAR} harfiah di stack lain.

Aturan parsing sekilas

Baris input	Nilai hasil parse	Aturan
PORT=8080	"8080"	Tanpa kutip, dipertahankan sebagai string (tanpa pemaksaan tipe)
APP_NAME=My App # title	"My App"	Tanpa kutip: komentar # sebaris dibuang, spasi di belakang dipangkas
GREETING="Hello,\nWorld"	Hello,⏎World	Kutip ganda memproses \n sebagai baris baru sungguhan
LITERAL='no \n escapes'	no \n escapes	Kutip tunggal bersifat harfiah, tanpa pemrosesan escape
COLOR=#ff0000	""	# tanpa kutip memulai komentar — nilainya hilang; kutiplah
export AWS_REGION=us-east-1	us-east-1	Awalan export dibuang
EMPTY=	""	Nilai kosong adalah string kosong yang sah

.env vs JSON config: kapan memakai yang mana

Jawaban jujurnya bukan “JSON lebih baik.” Keduanya memecahkan masalah yang berbeda. File .env itu datar, hanya string, ramah komentar, dan per-environment, dibuat untuk secret dan penimpaan (override) saat deploy. JSON itu bertingkat, bertipe, dan terstruktur, tetapi tidak punya komentar dan mudah ter-commit tanpa sengaja. Memilih di antara keduanya adalah inti dari keputusan env vs json config.

Apa yang tidak bisa dilakukan .env

Sebuah .env tidak bisa bertingkat, tidak bisa menyimpan array, dan tidak bisa membawa tipe yang sesungguhnya. Ia adalah daftar string yang datar. Jika konfigurasi Anda secara alami berkelompok, ratakan dengan konvensi awalan alih-alih membuatnya bertingkat: DB_HOST dan DB_PORT alih-alih objek db. Kuncinya tetap datar; pengelompokannya Anda rakit kembali di dalam kode.

Apa yang lebih unggul di JSON

JSON unggul ketika struktur menjadi intinya: objek bertingkat, array, serta angka, boolean, dan null yang sesungguhnya. Inilah format yang Anda validasi terhadap skema dan format yang darinya Anda hasilkan tipe. Jika Anda membutuhkan hierarki yang tidak bisa diungkapkan oleh file datar, JSON (atau YAML, yang dibahas di bawah) adalah perkakas yang tepat.

Matriks keputusan

Kebutuhan	.env	JSON	Alasan
Secret / kredensial	✅	⚠️	.env di-git-ignore sesuai konvensi; konfigurasi JSON mudah ter-commit tanpa sengaja
Penimpaan per-environment	✅	⚠️	Satu .env per environment adalah pola deploy yang standar
Struktur bertingkat	❌	✅	.env itu datar; JSON bertingkat secara native
Nilai bertipe (number/bool/null)	❌	✅	Nilai .env selalu string; JSON punya tipe yang sesungguhnya
Komentar sebaris	✅	❌	.env mendukung #; JSON tidak punya sintaks komentar
Validasi skema	⚠️	✅	Validasi setelah mengonversi .env→JSON; JSON divalidasi secara langsung

Mengonversi .env ke JSON dan sebaliknya

Mengonversi ke arah mana pun bersifat mekanis begitu Anda tahu aturannya. Pemetaannya 1:1 di level atas (setiap baris KEY=VALUE menjadi satu properti JSON), dan satu-satunya kerumitan adalah soal tipe dan penyusunan bertingkat.

.env → JSON

Setiap pasangan KEY=VALUE menjadi sebuah properti JSON. Secara default setiap nilai adalah string, setia pada apa yang dimuat dotenv saat runtime; tombol inferensi tipe yang opsional mempromosikan angka, boolean, dan null yang tanpa kutip. Hasilnya adalah objek yang datar. Anda melakukan ini untuk memasukkan konfigurasi ke perkakas yang hanya menerima JSON, mengimpor massal ke pengelola secret (secrets manager), memvalidasi terhadap skema, atau sekadar membaca .env yang berserakan sebagai data terstruktur. Konverter ENV ke JSON melakukan persis ini di dalam browser, dengan peringatan saat menemukan kunci ganda.

JSON → .env

Arah sebaliknya hanya menerima objek; array di level atas atau skalar telanjang tidak punya nama kunci untuk dipetakan ke variabel. Angka dan boolean ditulis telanjang (PORT=8080), null menjadi KEY= kosong, dan string apa pun yang mengandung spasi, #, baris baru, atau kutip otomatis diberi kutip ganda dan di-escape agar bolak-balik (round-trip) dengan aman. Objek dan array bertingkat tidak bisa hidup di dalam file datar, jadi masing-masing diserialisasi menjadi string JSON dan ditandai dengan peringatan. Sakelar opsional menormalkan kunci menjadi UPPER_SNAKE_CASE dan menambahkan awalan export. Konverter JSON ke ENV menangani semua ini.

Keamanan bolak-balik dan peringatan soal penyusunan bertingkat

Pemberian kutip otomatis ada agar sebuah nilai bertahan tanpa berubah melalui .env → JSON → .env. Berikut proses bolak-baliknya sebagai kode yang bisa dijalankan, sesuai perilaku konverter. Perhatikan bahwa PORT tetap menjadi string sepanjang siklus, persis seperti yang akan dimuat dotenv:

import { parse } from 'dotenv';

// 1. Start with a .env file as text
const envText = `DATABASE_URL=postgres://user:pass@localhost:5432/mydb
PORT=8080
GREETING="Hello, World"
NOTE="value with # hash"`;

// 2. .env -> JSON (dotenv.parse returns string values only)
const config = parse(envText);
console.log(JSON.stringify(config, null, 2));
// {
//   "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb",
//   "PORT": "8080",
//   "GREETING": "Hello, World",
//   "NOTE": "value with # hash"
// }

// 3. JSON -> .env (quote only strings that need it)
const needsQuotes = (s) => /[\s#"'\n]/.test(s);
const env = Object.entries(config)
  .map(([key, value]) =>
    needsQuotes(value) ? `${key}=${JSON.stringify(value)}` : `${key}=${value}`
  )
  .join('\n');

console.log(env);
// DATABASE_URL=postgres://user:pass@localhost:5432/mydb
// PORT=8080
// GREETING="Hello, World"
// NOTE="value with # hash"

Sisi peliknya adalah penyusunan bertingkat. Proses bolak-balik tidak kehilangan apa-apa untuk konfigurasi datar, tetapi struktur yang bertingkat dalam hanya bisa melewati .env sebagai string JSON yang buram, tak terbaca oleh aplikasi mana pun yang mengharapkan strukturnya kembali. Jika konfigurasi Anda memang benar-benar hierarkis, beralihlah ke YAML. Konverter YAML ke JSON dan Masalah Norway YAML membahas jalur itu beserta sisi-sisi peliknya sendiri.

Memvalidasi konfigurasi environment

Variabel konfigurasi yang hilang atau salah bentuk tidak seharusnya muncul sebagai undefined is not a function pada pukul 3 dini hari di production. Pendekatan Twelve-Factor adalah gagal cepat (fail fast): periksa konfigurasi sebelum deploy, bukan sesudahnya. Mengonversi .env ke JSON membuat hal itu praktis, karena JSON punya perkakas validasi yang matang, yang tidak dimiliki environment variable mentah.

Validasi skema di CI

Konversikan .env → JSON, lalu validasi JSON tersebut terhadap skema yang menyatakan kunci wajib, enum yang diizinkan, dan format nilai. Environment yang salah konfigurasi (DATABASE_URL yang hilang, LOG_LEVEL yang tidak valid, port yang bukan angka) akan gagal pada pemeriksaan CI alih-alih saat deploy. Validasi JSON Schema memandu cara menulis skemanya, dan JSON Schema Validator menjalankannya di dalam browser.

Konfigurasi bertipe

Selain pemeriksaan keberadaan, Anda bisa menurunkan objek konfigurasi bertipe sehingga process.env.PORT bukan lagi string tak bertipe yang berserakan di seluruh basis kode. Validasi dan paksa tipenya saat startup dengan pustaka skema runtime seperti Zod, atau hasilkan sebuah interface TypeScript dari JSON dan baca konfigurasi melaluinya. JSON ke TypeScript dan konverter Konverter JSON ke TypeScript membahas langkah pembuatannya. Cetak-rapi atau periksa kewarasan JSON-nya lebih dulu dengan JSON Formatter agar kejutan struktural muncul lebih awal.

Higiene secret: menangani .env dengan aman

Secara fungsional, sebuah .env adalah daftar kredensial. Perlakukan ia seperti itu.

Jangan pernah meng-commit .env. Tambahkan ke .gitignore. Commit-lah .env.example yang mendaftar setiap kunci dengan nilai kosong atau placeholder, misalnya DATABASE_URL= alih-alih string koneksi yang asli. File itu adalah kontrak tim: ia mendokumentasikan variabel apa saja yang dibutuhkan oleh sebuah clone baru tanpa membocorkan satu pun di antaranya.

.env untuk lokal dan dev; production memakai pengelola secret. Perkakas seperti Vault, Doppler, dan AWS Secrets Manager menyuntikkan secret ke dalam environment saat deploy. Jangan mengirim .env asli berisi secret hidup ke host production. Tariklah dari pengelolanya, sehingga file yang bocor atau kontainer yang salah konfigurasi tidak menyerahkan kunci Anda.

Hanya konversikan secret di perkakas yang sepenuhnya berjalan di browser. Menempel .env asli ke konverter sisi-server berarti mengirim kredensial Anda lewat jaringan ke mesin orang lain. Kedua konverter di sini berjalan sepenuhnya di browser Anda. Buka tab Network di DevTools dan pastikan bahwa menempel teks tidak memicu satu pun permintaan. Itulah perbedaan yang membuatnya aman untuk mengonversi .env production, bukan sekadar contoh yang sudah disanitasi.

FAQ

Bagaimana cara mengonversi file .env menjadi JSON?

Tempelkan file tersebut ke Konverter ENV ke JSON dan ia akan langsung mem-parse-nya menjadi JSON di dalam browser Anda. Setiap baris KEY=VALUE menjadi sebuah properti. Nilai-nilainya berupa string secara default (sesuai dotenv); aktifkan inferensi tipe jika Anda menginginkan angka dan boolean. Tidak ada yang diunggah, jadi secret asli tetap berada di perangkat Anda.

Apakah nilai .env itu angka dan boolean, atau string?

Selalu string. dotenv tidak pernah memaksakan tipe: saat runtime setiap nilai process.env adalah string, jadi PORT=8080 adalah "8080" dan DEBUG=false adalah string "false" (yang bernilai truthy). Opsi “infer types” apa pun adalah lapisan kenyamanan yang ditambahkan di atas standar, bukan bagian dari dotenv itu sendiri.

Apa perbedaan antara file .env dan file konfigurasi JSON?

Sebuah .env itu datar, hanya string, ramah komentar, dan dibuat untuk secret serta penimpaan per-environment. JSON itu bertingkat dan bertipe dengan angka, boolean, dan null yang sesungguhnya, serta divalidasi terhadap skema, tetapi tidak punya komentar dan mudah ter-commit tanpa sengaja. Gunakan .env untuk secret, JSON untuk konfigurasi terstruktur.

Bisakah file .env memiliki nilai bertingkat atau berkelompok?

Tidak. Sebuah .env adalah daftar pasangan KEY=VALUE yang datar tanpa penyusunan bertingkat dan tanpa array. Untuk mengungkapkan pengelompokan, ratakan dengan konvensi awalan (DB_HOST dan DB_PORT alih-alih objek db) dan rakit kembali strukturnya di dalam kode. Jika Anda memang benar-benar membutuhkan hierarki, gunakan JSON atau YAML.

Bagaimana kutip, # dan nilai multi-baris ditangani di .env?

Kutip ganda memproses escape (\n, \t, \\, \") dan bisa membentang ke beberapa baris sampai kutip penutup. Kutip tunggal bersifat harfiah tanpa escape. Nilai tanpa kutip berlaku sampai akhir baris, memangkas spasi di belakang, dan memperlakukan spasi-plus-# sebagai komentar sebaris, jadi kutiplah nilai apa pun yang memang sah mengandung #.

Haruskah saya meng-commit file .env ke Git?

Tidak. Tambahkan .env ke .gitignore dan commit-lah .env.example yang mendaftar kuncinya dengan nilai kosong. File aslinya menyimpan kata sandi basis data, kunci API, dan token; meng-commit-nya membocorkan kredensial ke dalam riwayat Anda, tempat ia tetap ada bahkan setelah Anda menghapus file tersebut.