@wolfstar/env-utilities

npm install @wolfstar/env-utilities

pnpm add @wolfstar/env-utilities

yarn add @wolfstar/env-utilities

bun add @wolfstar/env-utilities

npm

Source

Description

Functional utilities for reading and parsing environmental variables, based on Wolfstar’s internal tools.

Usage

Setup

To setup @wolfstar/env-utilities, you use the setup function exported by the package:

import { setup } from '@wolfstar/env-utilities';

// Finds src/.env* and .env* from the current project automatically.
setup();

Alternatively, if you do not need to provide any custom options you can import it as a side effect:

import '@wolfstar/env-utilities/setup';

You can also pass a string or if you want to define other options, you may use EnvSetupOptions. Optionally, you may configure dotenv via environment variables:

DOTENV_DEBUG: configures EnvSetupOptions.debug. If enabled, the library will log to help debug why certain keys or values are not being set as expected.
DOTENV_ENCODING: configures EnvSetupOptions.encoding. If set, it will specify the encoding of the files containing the environment variables
DOTENV_ENV: configures EnvSetupOptions.env. If set, it will specify a custom environment if NODE_ENV is not sufficient.
DOTENV_PATH: configures EnvSetupOptions.path. If set, it will specify a custom path to the file containing environment variables, useful for when they are located elsewhere.
DOTENV_PREFIX: configures EnvSetupOptions.prefix. If set, it will specify a required prefix for dotenv variables (e.g. APP_).

What `.env` files can be used?

Every file below is searched first under src/, then at the project root. An explicit path or DOTENV_PATH disables this discovery and uses that base path only.

.env: Default.
.env.local: Local overrides. This file is loaded for all environments except test.
.env.development, .env.test, .env.production: Environment-specific settings.
.env.development.local, .env.test.local, .env.production.local: Local overrides of environment-specific settings.

Files on the left have more priority than files on the right:

npm start: .env.development.local, .env.local, .env.development, .env
npm test: .env.test.local, .env.test, .env (note .env.local is missing)

CRA Reference

Typing Environment Variables

To add new entries, you augment Env from @wolfstar/env-utilities/dist/lib/types using any of the following types:

BooleanString: can be parsed with envParseBoolean.
IntegerString: can be parsed with envParseInteger.
NumberString: can be parsed with envParseNumber.
string: can be parsed with envParseString and envParseArray.

The above 5 functions will throw an ReferenceError instance if a key is missing (unless a default is passed in the second parameter) as well as a TypeError instance if a key could not be parsed. The default value is returned as-is and is not validated. An example of adding more keys is as it follows:

import type { BooleanString, IntegerString, NumberString } from '@wolfstar/env-utilities';

declare module '@wolfstar/env-utilities' {
	interface Env {
		// Accepts 'true' or 'false':
		ENABLE_TELEMETRY: BooleanString;

		// Accepts any integer, e.g. '10':
		REFRESH_INTERVAL: IntegerString;

		// Accepts any number, e.g. '1.5':
		MINIMUM_SPEED: NumberString;

		// Accepts any string:
		APPLICATION_SECRET: string;
	}
}

Infrastructure

Shared pieces

Platform helpers

Plugins

npm

Source

Description

Usage

Setup

What `.env` files can be used?

Typing Environment Variables

npm

Source

​Description

​Usage

​Setup

​What .env files can be used?

​Typing Environment Variables

Description

Usage

Setup

What `.env` files can be used?

Typing Environment Variables