.env File Parser
How it works
.env → JSON reads the file line by line. Blank lines and lines starting
with # are comments and are skipped; a leading export is stripped
so shell-style exports parse the same as a plain assignment. Every value comes back as a
string — .env has no other type to give it. A value wrapped in matching
quotes has them stripped, with double quotes additionally unescaping \n,
\" and \\; an unquoted value has an inline #comment
cut off and trailing whitespace trimmed.
JSON → .env expects a flat JSON object of string, number or boolean
values — a nested object or array has no .env representation, so it is reported as an
error rather than silently flattened. A value is wrapped in double quotes (with
escaping) only if it contains whitespace, #, or a quote character; otherwise
it is written bare.
Frequently asked questions
Why do single quotes and double quotes behave differently?
This matches how real dotenv-parsing libraries behave, not an arbitrary choice made here. A double-quoted value supports escape sequences — \n becomes a real newline, \" becomes a literal quote, \\ becomes a single backslash. A single-quoted value is taken completely literally: nothing inside it is ever processed as an escape, so 'raw\nvalue' keeps its literal backslash and n rather than becoming a newline.
Why does every value become a JSON string, even ones that look like a number or boolean?
.env has no type system at all — PORT=3000 is the three-character string "3000", not the number 3000, and DEBUG=true is the string "true", not a boolean. Converting it to a number or boolean here would be assuming something the file itself never actually says.
How are inline comments detected?
A # that follows an UNQUOTED value ends the value right there — everything after it on that line is a comment. A # inside a quoted value is just a literal character, not the start of a comment, since the quotes already say where the value ends.