nc.env

nc.env.parse()

parse(content: string, options?: EnvParseOptions): Record<string, string>

Parses the text of a .env file: quotes, multi-line values, export, comments, escapes, and ${VAR} expansion (except in single quotes).

Returns Record<string, string>

Example

env.parse('PORT=3000\nURL="http://localhost:${PORT}"');
// { PORT: "3000", URL: "http://localhost:3000" }

nc.env.load()

load(files?: string | string[], options?: EnvLoadOptions): Record<string, string>

Loads .env files into process.env. The first file to set a variable wins, and variables that are already set are kept, unless you pass override.

Returns Record<string, string>: Everything read from the files.

Throws Error If required is set and a file is missing.

Example

env.load();                                // ./.env
env.load([".env.local", ".env"]);          // local values win
env.load(".env.test", { override: true });

nc.env.get()

get(name: string, fallback?: string): string | undefined

Reads a variable, with a fallback. Never throws.

Returns string | undefined

Example

env.get("REGION", "eu-west-1");

nc.env.has()

has(name: string): boolean

Is the variable set, even to an empty string?

Returns boolean

nc.env.required()

required(name: string): string

Reads a variable that must be set and not empty.

Returns string

Throws ValidationError If it's missing or empty.

Example

const key = env.required("STRIPE_SECRET_KEY");

nc.env.string()

string(name: string, options?: (EnvGetterOptions<string> & { pattern?: RegExp; minLength?: number; }) | undefined): string

Reads a string. Required unless you give a default or optional.

Returns string

Throws ValidationError

Example

env.string("APP_NAME", { default: "my-app" });

nc.env.number()

number(name: string, options?: (EnvGetterOptions<number> & { min?: number; max?: number; integer?: boolean; }) | undefined): number

Reads a number.

Returns number

Throws ValidationError

Example

env.number("WORKERS", { default: 4, min: 1, integer: true });

nc.env.bool()

bool(name: string, options?: EnvGetterOptions<boolean>): boolean

Reads a boolean: true/false, 1/0, yes/no or on/off.

Returns boolean

Throws ValidationError

Example

if (env.bool("FEATURE_BETA", { default: false })) enableBeta();

nc.env.port()

port(name: string, options?: EnvGetterOptions<number>): number

Reads a port number.

Returns number

Throws ValidationError

Example

server.listen(env.port("PORT", { default: 3000 }));

nc.env.url()

url(name: string, options?: (EnvGetterOptions<string> & { protocols?: string[]; }) | undefined): string

Reads an absolute URL.

Returns string

Throws ValidationError

Example

env.url("DATABASE_URL", { protocols: ["postgres", "postgresql"] });

nc.env.duration()

duration(name: string, options?: EnvGetterOptions<string | number>): number

Reads a duration like "30s" or "1h30m" and returns milliseconds.

Returns number

Throws ValidationError

Example

env.duration("CACHE_TTL", { default: "10m" }); // 600000

nc.env.list()

list(name: string, options?: (EnvGetterOptions<string[]> & { separator?: string; }) | undefined): string[]

Reads a comma-separated list. Items are trimmed and empty ones dropped.

Returns string[]

Throws ValidationError

Example

// ALLOWED_ORIGINS="https://a.com, https://b.com"
env.list("ALLOWED_ORIGINS", { default: [] }); // ["https://a.com", "https://b.com"]

nc.env.json()

json<T = any>(name: string, options?: EnvGetterOptions<T>): T

Reads a JSON value.

Returns T

Throws ValidationError

Example

const flags = env.json("FEATURE_FLAGS", { default: {} });

nc.env.oneOf()

oneOf<V extends string>(name: string, values: readonly V[], options?: EnvGetterOptions<V>): V

Reads a variable that must be one of the given values. The result has their literal type.

Returns V

Throws ValidationError

Example

env.oneOf("LOG_LEVEL", ["debug", "info", "warn", "error"], { default: "info" });

nc.env.validate()

validate<T extends Record<string, EnvVarSpec>>(spec: T, options?: { env?: ProcessEnv; } | undefined): Readonly<EnvConfig<T>>

Checks all your variables at once and returns a typed, frozen config. If anything is wrong, one ValidationError lists every problem, so a bad deployment fails at startup with the full picture.

Returns Readonly<EnvConfig<T>>

Throws ValidationError

Example

const config = env.validate({
  NODE_ENV: { type: "enum", values: ["development", "production", "test"], default: "development" },
  PORT: { type: "port", default: 3000 },
  DATABASE_URL: { type: "url", protocols: ["postgres"] },
  JWT_SECRET: { type: "string", minLength: 32 },
  SENTRY_DSN: { type: "url", optional: true },
});
// ValidationError: Validation failed with 2 issues:
//   • DATABASE_URL: is required but is not set
//   • JWT_SECRET: must contain at least 32 characters

nc.env.mode()

mode(): string

NODE_ENV, or "development" when it's not set.

Returns string

nc.env.isProduction()

isProduction(): boolean

Is NODE_ENV set to "production"?

Returns boolean

nc.env.isDevelopment()

isDevelopment(): boolean

Is NODE_ENV "development", or not set?

Returns boolean

nc.env.isTest()

isTest(): boolean

Are we running tests? True when NODE_ENV is "test" or a test runner like node --test or Jest is detected.

Returns boolean