@skyra/env-utilities
Functional utilities for reading and parsing environmental variables, based on Skyra's internal tools.
Usage
Setup
To setup @skyra/env-utilities
, you use the setup
function exported by the package:
import { setup } from '@skyra/env-utilities';
// Set the path as the `.env` file besides the current module:
// NOTE: If not set, it defaults to dotenv's default, `path.resolve(process.cwd(), '.env')`.
setup(new URL('.env', import.meta.url));
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
: configuresEnvSetupOptions.debug
. If enabled, the library will log to help debug why certain keys or values are not being set as expected. -
DOTENV_ENCODING
: configuresEnvSetupOptions.encoding
. If set, it will specify the encoding of the files containing the environment variables -
DOTENV_ENV
: configuresEnvSetupOptions.env
. If set, it will specify a custom environment ifNODE_ENV
is not sufficient. -
DOTENV_PATH
: configuresEnvSetupOptions.path
. If set, it will specify a custom path to the file containing environment variables, useful for when they are located elsewhere. -
DOTENV_PREFIX
: configuresEnvSetupOptions.prefix
. If set, it will specify a required prefix for dotenv variables (e.g.APP_
).
.env
files can be used?
What -
.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)
Typing Environment Variables
To add new entries, you augment Env
from @skyra/env-utilities/dist/lib/types
using any of the following types:
-
BooleanString
: can be parsed withenvParseBoolean
. -
IntegerString
: can be parsed withenvParseInteger
. -
NumberString
: can be parsed withenvParseNumber
. -
string
: can be parsed withenvParseString
andenvParseArray
.
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 '@skyra/env-utilities';
declare module '@skyra/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;
}
}