Config Parser
A set of utilities for parsing environment variables at runtime into type-safe configuration objects.
Problem
The Twelve-Factor App Methodology prescribes storing configuration in the environment separate from the application code. However, it is impossible to know the types of the environment variables at runtime in a JavaScript application. For example, all of the keys of the process.env
object in a Node.js runtime must be either string
or undefined
.
Solution
By parsing the runtime environment variables into a typed object on application startup, we can adopt a fail-fast design and guarantee type safety within the application code. This allows us to detect configuration issues on startup and enjoy the benefits of intelligent code completion.
Installation
# Install with NPM
npm install --save @laeri/config-parser
# Install with Yarn
yarn add @laeri/config-parser
Usage
Specify the config object
The typed config object provides a place to document your environment variables in code. These comments should be available via intelligent code completion.
// config.ts
export const config = {
/**
* The name of the application.
* @example "my-app"
*/
applicationName: parseToString('APPLICATION_NAME'),
/**
* The port the application is listening for requests on.
* @example 1337
*/
port: parseToInteger('PORT'),
/**
* True if application tracing is enabled.
* @example false
*/
isTracingEnabled: parseToBoolean('IS_TRACING_ENABLED'),
}
The parsing functions included in this utility library throw exceptions if the value is missing or cannot be parsed.
Use the config object in your application
The config object is now ready to use anywhere you need it.
// server.ts
import { app } from './app'
import { config } from './config'
app.listen(config.port, () => {
console.log(`Application listening on port ${config.port}.`)
})
This library has no dependencies but it can be used in conjunction with libraries like
dotenv
.
process.env
directly (optional)
Prevent accessing You can add a linter rule to your eslintrc.json
file to discourage accessing the process.env
object directly.
{
"extends": [
"eslint:recommended",
"plugin:node/recommended"
],
"parserOptions": {
"ecmaVersion": 2020
},
"rules": {
"node/no-process-env": ["error", "always"],
...
}
}
This linter rule requires
eslint-plugin-node
.
Parsers
-
parseToString
: parses an environment variable to astring
type (e.g."http://localhost" => "http://localhost"
) -
toBoolean
: parses an environment variable to aboolean
type (e.g."true" => true
) -
toFloat
: parses an environment variable to anumber
type (e.g."12.75" => 12.75
) -
toInteger
: parses an environment variable to an integer (e.g."42" => 42
)
Exceptions
-
MissingEnvironmentVariableException
: thrown if an environment variable is missing -
ParserException
: thrown if an environment variable fails to parse
Contributions
Contributions are encouraged! Feel free to open a PR following our contribution guidelines if you want to add a new parser.