@skyra/env-utilities v1.3.0
@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 variablesDOTENV_ENV
: configuresEnvSetupOptions.env
. If set, it will specify a custon 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_
).
What .env
files can be used?
.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;
}
}