.env-bestanden uitgelegd: parsing, JSON-conversie & config

Een .env-bestand is een platte tekstlijst van KEY=VALUE-paren die configuratie en geheimen buiten je broncode houdt. Het is het formaat dat Node, Vite, Next.js, Python, Ruby en Docker Compose in de procesomgeving laden. Zoek je op env to json, dan wil je meestal een van twee dingen: een .env omzetten naar gestructureerde JSON voor je tooling, of de regels goed genoeg begrijpen om het veilig te doen.

Drie dingen zorgen telkens voor verwarring, dus die nemen we eerst weg:

1. Een .env-bestand is plat. Er is geen nesting. Elke key staat op het hoogste niveau.
2. Elke waarde is een string. dotenv zet types nooit om. PORT=8080 laadt als "8080", niet als 8080.
3. De grammatica is informeel. Er is geen formele spec, dus loaders verschillen aan de randen: quotes, comments, escapes.

Deze gids behandelt de dotenv-parsingregels, de .env↔JSON-mapping (en waarom je beide kanten op zou converteren), een keuzematrix voor wanneer je .env versus JSON gebruikt en hoe je je config valideert voordat hij live gaat. Alles wat hier wordt beschreven, gebeurt in de ENV naar JSON Converter volledig in je browser, zodat zelfs een .env vol echte credentials de pagina nooit verlaat.

Wat is een .env-bestand?

Het .env-bestand is de de-facto standaard voor omgevingsconfiguratie. De dotenv-library, en haar ports naar bijna elke taal, leest het bestand en injecteert elk paar in het draaiende proces. Je app leest dan process.env.DATABASE_URL in plaats van de connectiestring hard te coderen. Omdat het bestand databasewachtwoorden, API-keys, OAuth-geheimen en access tokens bevat, staat het bijna altijd in git-ignore en wordt het als gevoelig behandeld.

Anatomie van een regel

Elke betekenisvolle regel is een KEY=VALUE-paar, gesplitst op het eerste =-teken. Comment-regels en lege regels worden overgeslagen en een optionele export-prefix wordt verwijderd:

# 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"

De key is alles vóór de eerste =, ontdaan van omringende witruimte. De export-prefix bestaat zodat het bestand direct in een shell ge-sourced kan worden; dotenv-loaders verwijderen hem automatisch. Splitsen op de eerste = is belangrijk, omdat waarden zoals DATABASE_URL vaak hun eigen =-tekens in query strings bevatten.

Waarom config in de omgeving leeft

De redenering komt uit de Twelve-Factor App, die zegt config in de omgeving op te slaan. Config verandert per deploy (dev, staging, productie) terwijl de code hetzelfde blijft. Door het in de omgeving te houden wijzig je een databasehost zonder broncode te bewerken of opnieuw te deployen, en draait dezelfde build overal.

Een veelgemaakte verkeerde lezing: mensen citeren “config nooit in een bestand” en concluderen dat .env verboden is. De echte regel is smaller. Config hoort geen bestand te zijn dat binnen de app is gecommit, vermengd met code en bijgehouden in versiebeheer. Een lokale, git-ignored .env voor development is prima en standaard. Wat je vermijdt, is een echte .env met geheimen erin naar productie sturen.

.env-parsingregels (de randgevallen waarover tools het oneens zijn)

Omdat er geen formele spec is om een .env-bestand tegen af te toetsen, neemt elke loader zijn eigen beslissingen aan de grenzen. De onderstaande regels zijn de breed gevolgde dotenv-conventies: degene die de converter implementeert en waarover de meeste runtimes het eens zijn.

Quotes en escapes

Hoe een waarde wordt gequote, verandert alles:

• Dubbele quotes verwerken escape-sequenties. \n wordt een newline, \t een tab, \r een carriage return, \\ een backslash en \" een letterlijke dubbele quote. Een waarde tussen dubbele quotes kan ook over meerdere regels lopen tot de sluitende quote, en zo passen PEM private keys in een .env.
• Enkele quotes zijn letterlijk. Er gebeurt geen escape-verwerking, precies zoals in de shell. 'no \n escapes here' behoudt de backslash en de n letterlijk.
• Niet-gequote waarden lopen tot het einde van de regel, waarbij trailing witruimte wordt verwijderd. Een inline # (een spatie gevolgd door een hash) start een comment die eraf wordt geknipt.

Die laatste regel speelt mensen parten bij hex-kleuren. COLOR=#ff0000 verliest alles na de #. Zet er quotes omheen (COLOR="#ff0000") en de waarde overleeft.

Alles is een string

Dit is het allerbelangrijkste feit over het dotenv-formaat. PORT=8080 laadt niet als het getal 8080. Het laadt als de string "8080", omdat process.env-waarden tijdens runtime altijd strings zijn. dotenv zet types nooit om.

Dit veroorzaakt echte bugs. if (process.env.DEBUG) is truthy, zelfs als DEBUG=false, omdat "false" een niet-lege string is. Numerieke vergelijkingen mislukken stilletjes, want "8080" is niet 8080. Elke “infer types”-functie, inclusief de schakelaar in de converter, is een gemakslaag bovenop dotenv, geen onderdeel van de standaard. Gebruik hem bewust, in de wetenschap dat de JSON dan afwijkt van wat je app daadwerkelijk ontvangt.

Dubbele keys, multi-line waarden en interpolatie

Wanneer dezelfde key twee keer voorkomt, wint het laatste voorkomen. De eerdere waarde wordt stilletjes weggegooid. Dit is een veelvoorkomende misconfiguratie-valkuil: een verdwaalde dubbele key onderaan een lang bestand overschaduwt geruisloos de waarde die je bedoelde. Een goede converter signaleert dubbele keys met een waarschuwing in plaats van ze in te slikken.

Multi-line waarden werken alleen binnen dubbele quotes, lopend over regels tot de sluitende ". En ${VAR}-interpolatie (de ene variabele vanuit een andere refereren) bestaat in sommige loaders, maar is niet universeel. Vertrouw er niet op tussen runtimes; een bestand dat prima interpoleert in de ene stack laadt mogelijk de letterlijke string ${VAR} in een andere.

Parsingregels in één oogopslag

Invoerregel	Geparste waarde	Regel
PORT=8080	"8080"	Niet-gequote, behouden als string (geen type-omzetting)
APP_NAME=My App # title	"My App"	Niet-gequote: inline #-comment verwijderd, trailing spatie weggehaald
GREETING="Hello,\nWorld"	Hello,⏎World	Dubbele quotes verwerken \n als een echte newline
LITERAL='no \n escapes'	no \n escapes	Enkele quotes zijn letterlijk, geen escape-verwerking
COLOR=#ff0000	""	Niet-gequote # start een comment, dus de waarde gaat verloren; zet er quotes omheen
export AWS_REGION=us-east-1	us-east-1	export-prefix verwijderd
EMPTY=	""	Lege waarde is een geldige lege string

.env versus JSON-config: wanneer gebruik je wat

Het eerlijke antwoord is niet “JSON is beter”. Ze lossen verschillende problemen op. Een .env-bestand is plat, alleen-strings, comment-vriendelijk en per omgeving, gebouwd voor geheimen en deploy-time-overrides. JSON is genest, getypeerd en gestructureerd, maar kent geen comments en is makkelijk per ongeluk te committen. Tussen die twee kiezen is de echte env vs json config-beslissing.

Wat .env niet kan

Een .env kan niet nesten, kan geen arrays bevatten en kan geen echte types dragen. Het is een platte lijst strings. Is je config van nature gegroepeerd, dan maak je hem plat met een prefix-conventie in plaats van te nesten: DB_HOST en DB_PORT in plaats van een db-object. De keys blijven plat; de groepering stel je in code weer samen.

Waar JSON beter in is

JSON wint wanneer structuur het punt is: geneste objecten, arrays en echte getallen, booleans en null. Het is het formaat dat je tegen een schema valideert en waaruit je types genereert. Heb je een hiërarchie nodig die een plat bestand niet kan uitdrukken, dan is JSON (of YAML, hieronder behandeld) het juiste gereedschap.

Keuzematrix

Behoefte	.env	JSON	Waarom
Geheimen / credentials	✅	⚠️	.env staat per conventie in git-ignore; JSON-config is makkelijk per ongeluk te committen
Per-omgeving-overrides	✅	⚠️	Eén .env per omgeving is het standaard deploy-patroon
Geneste structuur	❌	✅	.env is plat; JSON nest van nature
Getypeerde waarden (number/bool/null)	❌	✅	.env-waarden zijn altijd strings; JSON heeft echte types
Inline comments	✅	❌	.env ondersteunt #; JSON heeft geen comment-syntaxis
Schemavalidatie	⚠️	✅	Valideer na het omzetten van .env→JSON; JSON valideert direct

.env naar JSON converteren en terug

Converteren in beide richtingen is mechanisch zodra je de regels kent. De mapping is 1:1 op het hoogste niveau (elke KEY=VALUE-regel is één JSON-property) en de enige subtiliteit zijn types en nesting.

.env → JSON

Elk KEY=VALUE-paar wordt een JSON-property. Standaard is elke waarde een string, trouw aan wat dotenv tijdens runtime laadt; een optionele type-inferentie-schakelaar promoveert niet-gequote getallen, booleans en null. Het resultaat is een plat object. Je doet dit om config te voeden aan JSON-only-tooling, in bulk te importeren in een secrets manager, te valideren tegen een schema, of gewoon om een uitdijende .env als gestructureerde data te lezen. De ENV naar JSON Converter doet precies dit in de browser, met een waarschuwing als hij dubbele keys opmerkt.

JSON → .env

De omgekeerde richting neemt alleen een object, want een top-level array of kale scalar heeft geen keynamen om naar variabelen te mappen. Getallen en booleans worden kaal geschreven (PORT=8080), null wordt een lege KEY=, en elke string die een spatie, #, newline of quote bevat, wordt automatisch tussen dubbele quotes gezet en ge-escaped zodat hij veilig terugloopt. Geneste objecten en arrays kunnen niet in een plat bestand leven, dus elk wordt geserialiseerd naar een JSON-string en met een waarschuwing gemarkeerd. Optionele schakelaars normaliseren keys naar UPPER_SNAKE_CASE en voegen een export-prefix toe. De JSON naar ENV Converter regelt dit allemaal.

Veilig heen en terug en de nesting-kanttekening

De automatische quoting bestaat zodat een waarde de cyclus .env → JSON → .env ongewijzigd overleeft. Hier is die heen-en-terug als uitvoerbare code, overeenkomend met het gedrag van de converters. Let op dat PORT een string blijft door de cyclus heen, precies zoals dotenv hem zou laden:

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"

Het addertje is nesting. De heen-en-terug is verliesvrij voor platte config, maar een diep geneste structuur kan alleen door .env heen als ondoorzichtige JSON-strings, onleesbaar voor elke app die de structuur terug verwacht. Is je config echt hiërarchisch, grijp dan naar YAML. De YAML naar JSON Omzetter en de gids Het YAML Norway-probleem behandelen dat pad en zijn eigen scherpe randen.

Omgevingsconfig valideren

Een ontbrekende of misvormde config-variabele hoort niet om 3 uur ‘s nachts in productie op te duiken als undefined is not a function. De Twelve-Factor-aanpak laat je fail fast: controleer config vóór de deploy in plaats van erna. .env naar JSON omzetten maakt dat praktisch, want JSON heeft volwassen validatie-tooling die kale environment-variabelen niet hebben.

Schema-valideren in CI

Zet .env → JSON om en valideer de JSON vervolgens tegen een schema dat verplichte keys, toegestane enums en waardeformaten declareert. Een verkeerd geconfigureerde omgeving (een ontbrekende DATABASE_URL, een ongeldige LOG_LEVEL, een port die geen getal is) laat de CI-controle falen in plaats van de deploy. De gids JSON Schema-validatie loopt door het schrijven van het schema, en de JSON Schema Validator draait het in de browser.

Getypeerde config

Verder dan aanwezigheidscontroles kun je een getypeerd config-object afleiden, zodat process.env.PORT geen ongetypeerde string is die verspreid door de codebase ligt. Valideer en zet om bij het opstarten met een runtime-schemalibrary als Zod, of genereer een TypeScript-interface uit de JSON en lees config daardoorheen. De gids JSON naar TypeScript en de JSON naar TypeScript Omzetter behandelen de generatiestap. Print de JSON eerst netjes uit of controleer hem op gezond verstand met de JSON Formatter, zodat een structurele verrassing vroeg aan het licht komt.

Geheimenhygiëne: een .env veilig behandelen

Een .env is functioneel een lijst credentials. Behandel hem ook zo.

Commit nooit een .env. Voeg hem toe aan .gitignore. Commit een .env.example die elke key opsomt met lege of placeholder-waarden, bijvoorbeeld DATABASE_URL= in plaats van de echte connectiestring. Dat bestand is het teamcontract: het documenteert welke variabelen een nieuwe clone nodig heeft zonder er een te lekken.

.env is voor lokaal en dev; productie gebruikt een secrets manager. Tools als Vault, Doppler en AWS Secrets Manager injecteren geheimen in de omgeving op deploy-time. Stuur geen echte .env met live geheimen naar een productiehost. Haal ze in plaats daarvan uit de manager, zodat een gelekt bestand of een verkeerd geconfigureerde container je keys niet weggeeft.

Converteer geheimen alleen in een browser-only-tool. Een echte .env in een server-side-converter plakken stuurt je credentials over het netwerk naar iemand anders zijn machine. Beide converters hier draaien volledig in je browser. Open het tabblad Network in DevTools en bevestig dat plakken nul aanvragen oplevert. Dat is het verschil dat het veilig maakt om een productie-.env te converteren in plaats van een opgeschoond voorbeeld.

FAQ

Hoe converteer ik een .env-bestand naar JSON?

Plak het bestand in de ENV naar JSON Converter en het wordt direct in je browser naar JSON geparset. Elke KEY=VALUE-regel wordt een property. Waarden zijn standaard strings (overeenkomend met dotenv); zet type-inferentie aan als je getallen en booleans wilt. Er wordt niets geüpload, dus echte geheimen blijven op je apparaat.

Zijn .env-waarden getallen en booleans, of strings?

Altijd strings. dotenv zet types nooit om: tijdens runtime is elke process.env-waarde een string, dus PORT=8080 is "8080" en DEBUG=false is de string "false" (die truthy is). Elke “infer types”-optie is een gemakslaag bovenop de standaard, geen onderdeel van dotenv zelf.

Wat is het verschil tussen een .env-bestand en een JSON-configbestand?

Een .env is plat, alleen-strings, comment-vriendelijk en gebouwd voor geheimen en per-omgeving-overrides. JSON is genest en getypeerd met echte getallen, booleans en null, en valideert tegen een schema, maar kent geen comments en is makkelijk per ongeluk te committen. Gebruik .env voor geheimen, JSON voor gestructureerde config.

Kan een .env-bestand geneste of gegroepeerde waarden hebben?

Nee. Een .env is een platte lijst van KEY=VALUE-paren zonder nesting en zonder arrays. Om groepering uit te drukken, maak je hem plat met een prefix-conventie (DB_HOST en DB_PORT in plaats van een db-object) en stel je de structuur in code weer samen. Heb je echt een hiërarchie nodig, gebruik dan JSON of YAML.

Hoe worden quotes, # en multi-line waarden in .env afgehandeld?

Dubbele quotes verwerken escapes (\n, \t, \\, \") en kunnen over meerdere regels lopen tot de sluitende quote. Enkele quotes zijn letterlijk, zonder escapes. Niet-gequote waarden lopen tot het einde van de regel, halen trailing witruimte weg en behandelen een spatie-plus-# als een inline comment. Zet dus quotes om elke waarde die legitiem een # bevat.

Moet ik mijn .env-bestand naar Git committen?

Nee. Voeg .env toe aan .gitignore en commit in plaats daarvan een .env.example die de keys met lege waarden opsomt. Het echte bestand bevat databasewachtwoorden, API-keys en tokens; het committen lekt credentials in je geschiedenis, waar ze blijven bestaan zelfs nadat je het bestand hebt verwijderd.