Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Inlustra/env-args
Combining well known libs to load config through arguments, .env and environment variables. Handling naming for you.
https://github.com/Inlustra/env-args
Last synced: 4 months ago
JSON representation
Combining well known libs to load config through arguments, .env and environment variables. Handling naming for you.
- Host: GitHub
- URL: https://github.com/Inlustra/env-args
- Owner: Inlustra
- Created: 2018-01-20T20:24:01.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2018-01-26T14:35:12.000Z (about 7 years ago)
- Last Synced: 2024-10-28T16:01:27.498Z (4 months ago)
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@inlustra/env-args
- Size: 192 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# [@inlustra/env-args](https://www.npmjs.com/package/@inlustra/env-args)
Load configuration through arguments, a .env file and environment variables in that order. Handling naming for you.
By default, env-args will output logging information, and inform you if you're missing required arguments or environment variables.
## Installation
```BASH
npm install --save @inlustra/env-args
```
## More in-depth
An opinionated mechanism to load configuration from a given default configuration.
By default, environment variables are prefixed with your package name (in package.json)
Will automatically coerce both args and environment variables to their correct types:
- `--myVar='3000'`: would become `{myVar: 3000}`
- `--myVar='a full on string'`: would become `{myVar: 'a full on string'}`
- `--myVar=null`: would become `{myVar: null}`
- `--myVar=undefined`: would become `{myVar: undefined}`
- `--myVar='{test: 10}'`: would become `{myVar: {test: 10}}`
- `--myVar=user1 --myVar=user2`: would become `{myVar: ['user1', 'user2']`
- As an environment variable: `MY_VAR=["user1", "user2"]`
Uses:
- [minimist](https://www.npmjs.com/package/minimist) to parse the arguments
- [dotenv](https://www.npmjs.com/package/dotenv) to parse the .env file
### Short Example
Starting a project named `exampleProject`
Providing the following configuration to the load method: `{required: undefined}`
Running via npm (`npm start`) would require either an environment variable set as `EXAMPLE_PROJECT_REQUIRED` or the `--required='my var'` command line argument set.
Running a node script (`node index.js`) would require either an environment variable set as `REQUIRED` or the `--required='my var'` command line argument set.
All of this can be changed in using the provided configuration
### Full Example
This example can be run by using `npm i && npm start`
**With `package.json > name` set to `@inlustra/env-args`**
**index.js**
```javascript
const envArgs = require('@inlustra/env-args')
const defaultConfiguration = {
foo: 'A default string',
notRequired: null,
requiredNumber: undefined, // Passed in through .env file above
alsoRequired: undefined, // Passed in through args below
aNumber: undefined, // Passed in through args below
overridden: 10 // Passed in through both, args, and .env file (Args takes preference)
}
const loadedConfiguration = envArgs.load(defaultConfiguration, {
envPrefix: 'ENV_ARGS'
})
console.dir(loadedConfiguration)
```
**.env**
```
INLUSTRA_ENV_ARGS_REQUIRED_NUMBER=92
INLUSTRA_ENV_ARGS_OVERRIDDEN=This shouldnt appear
```
**Command Line**
`node index.js --alsoRequired="Fixed" --aNumber="4000" --overriden=wooh!`
**Output**
```
------------ Start Environment Configuration ------------
overridden: wooh!
aNumber: 4000
alsoRequired: Fixed
requiredNumber: 92
notRequired: null
foo: A default string
------------ End Environment Configuration --------------
{ overridden: 'wooh!',
aNumber: 4000,
alsoRequired: 'Fixed',
requiredNumber: 92,
notRequired: null,
foo: 'A default string' }
```
**Example output if arguments not supplied**
```
------------ Environment configuration not set ------------
Remember, you can override these by placing a .env file in your package.
Argument --alsoRequired or environment variable ENV_ARGS_ALSO_REQUIRED
Argument --aNumber or environment variable ENV_ARGS_A_NUMBER
/Users/the_nairn/Documents/Projects/envOrArgs/dist/index.js:58
throw new EnvironmentNotSetError();
^
Error: Missing environment configuration
```
## Configuration
| Key | Type | Description | Defaults To |
|------------------|:--------------------:|-------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| arguments | `string[]` | The arguments to be parsed by minimist | `process.env.slice(2)` |
| envPrefix | `string` | Used to override the environment variable, example: `required` would become `prefixrequired` when overriden | package name in constant format if run through npm, otherwise, empty. |
| throwUndefined | `boolean` | Will enable/disable exceptions when there is missing config | `true` |
| logConfiguration | `boolean` | Will enable/disable the default logging once loaded | `true` |
| log | `(string) => any` | Used to override the default logger | `console.log` |
| envKeyTransform | `(string) => string` | Used to completely customise configuration key to environment variable mapping | If package name exists, `PACKAGE_NAME_FIELD`, if it doesn't exist, but envPrefix is set: `ENV_PREFIX_FIELD` otherwise `FIELD` |
| dotEnvPath | `string` | Passed to dotenv to specify the location of the .env file | `undefined` (`.env`) |
| dotEnvEncoding | `'utf8' | 'base64'` | Passed to dotenv to specify the encoding of the variables in the dotenvfile | `undefined` (`'utf8'`) |
## Running tests
```bash
npm i
npm test
```