Skip to main content
Deno 2 is finally here 🎉️
Learn more

dotenv-parser

GitHub Workflow Status GitHub release (latest by date including pre-releases) GitHub code size in bytes deno doc GitHub

nest badge

A fast, zero-permission parser for ‘.env’ files with support for multiline variables.

Usage

Import

Import dotenv-parser from one of the following registries:

// From Deno.land
import { dotEnvParser } from "https://deno.land/x/dotenv_parser@v1.0.2/mod.ts";

// From Nest.land
import { dotEnvParser } from "https://x.nest.land/dotenv-parser@v1.0.2/mod.ts";

// From Denopkg
import { dotEnvParser } from "https://denopkg.com/ymonb1291/dotenv-parser@v1.0.2/mod.ts";

// From Github
import { dotEnvParser } from "https://raw.githubusercontent.com/ymonb1291/dotenv-parser/v1.0.2/mod.ts";

Read the .env file

dotenv-parser doesn’t ship with a way to read files. You must decode your .env file on your own.

For example:

const decoder = new TextDecoder("utf-8");
const raw = Deno.readFileSync(".env");
const data = decoder.decode(raw);
console.log(dotEnvParser(data));

For the purpose of this documentation, we’ll simply declare a string variable that contains the configuration.

For example:

const config = `
  SERVER_HOST=localhost
  SERVER_PORT=3000
  SERVER_HTTPS=true
`;

Parsing

The dotEnvParser function looks for KEY=VALUE pairs in a string and returns them as an object where all keys and values are of type string:

const res = dotEnvParser(config);
console.log(res);
//  Output:
//    { SERVER_HOST: "localhost", SERVER_PORT: "3000", SERVER_HTTPS: "true" }

DotEnvParser can also try accept a second boolean parameter. When true, the parser will try to infer the type of the value. Numbers and booleans will then be converted to their respective type:

const res = dotEnvParser(config, true);
console.log(res);
//  Output:
//    { SERVER_HOST: "localhost", SERVER_PORT: 3000, SERVER_HTTPS: true }

dotEnvParser

The parser has the following signature

function dotEnvParser<false>(raw: string): Data;
function dotEnvParser<false>(raw: string, infer: false): Data;
function dotEnvParser<true>(raw: string, infer: true): TypedData;

Data interface

Data describes the object returned when the infer parameter is false or undefined. It describes a plain object where all values are of type string.

interface Data {
  [key: string]: string;
}

TypedData interface

TypedData describes the object returned when the infer parameter is true. It describes a plain object where the values can be of type string, number or boolean.

interface TypedData {
  [key: string]: string | number | boolean;
}

Parsing rules

The parser supports key/value pairs formatted as KEY=VALUE. The following rules apply:

  • Empty lines are skipped
  • Lines beginning with # are treated as comments and are skipped
  • KEY=VALUE becomes {KEY="VALUE"}
    • Single quoted values can also be used: KEY='VALUE' also becomes {KEY="VALUE"}
    • Double quoted values can also be used: KEY="VALUE" also becomes {KEY="VALUE"}
  • Keys can contain upper case letters A-Z, lower case letters a-z and underscore character _. Numbers 0-9 are also valid when not in first position. For example:
    • _Key0=VALUE is valid and becomes {_Key0="VALUE"}
    • 0Key_=VALUE is not valid
  • Empty values are treated as empty string. EMPTY= becomes {EMPTY=""}
  • Single and double quoted values keep their surrounding spaces. Non quoted values do not.
    • KEY= VALUE becomes {KEY="VALUE"}
    • KEY=" VALUE " becomes {KEY=" VALUE "}
  • Inner quotes are maintained. JSON={"KEY": "VALUE"} becomes {JSON="{\"KEY\": \"VALUE\"}"}
  • Multiline values are accepted with and without quotes. For example:
    SAY_HELLO=Hello
    World!
    becomes {SAY_HELLO: "Hello\nWorld!"}
  • Multiline values can contain = if escaped
    CALC=1+1
    \\=2
    becomes {CALC: "1+1\n=2"}
  • Multiline values can contain # if escaped
    HASH=Hello
    \\#World
    becomes {HASH: "Hello\n#World"}

Contributions

PRs are welcome!