Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/efstajas/validate-env
🚓📋⚠️ A simple node.js utility that type-checks your process.env variables based on a .env.template file.
https://github.com/efstajas/validate-env
environment-variables nodejs nodejs-modules typescript utility validation validator
Last synced: 2 months ago
JSON representation
🚓📋⚠️ A simple node.js utility that type-checks your process.env variables based on a .env.template file.
- Host: GitHub
- URL: https://github.com/efstajas/validate-env
- Owner: efstajas
- License: apache-2.0
- Created: 2020-05-03T13:25:43.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-12-21T16:08:48.000Z (about 1 year ago)
- Last Synced: 2024-04-25T16:03:06.121Z (9 months ago)
- Topics: environment-variables, nodejs, nodejs-modules, typescript, utility, validation, validator
- Language: TypeScript
- Homepage:
- Size: 26.4 KB
- Stars: 17
- Watchers: 3
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🚓 validate-env
A small utility for checking process.env based on a .env.template file in node.js. You can use it to make sure all your env variables are set before running your application, and optionally ensure they're of the right types too.
## ⬇️ Install
Simply install with npm or yarn. validate-env is available on the NPM registry and on GitHub Packages.
```
npm install @efstajas/validate-env
or
yarn add @efstajas/validate-env
```
## 🎬 Getting started
First, create your `.env.template` file. This file contains all the .env variables you want to validate for. While you should never commit a .env file, committing the .env.template makes a lot of sense — everyone working on your project can see immediately what values they need, and validation will work as expected on any client. An example `.env.template` might look something like this:
```
FOO=string
BAR=number
FOOBAR=array
FOOBARFOO=boolean?
```
This `.env.template` means you expect all the variables FOO, BAR, and FOOBAR to exist. The `?` at the end of the FOOBARFOO variable's type means that it's an optional value — so, validation won't fail if it's not set, but if it is, it must be of type `boolean`. As you can see, after the =, you can specify a type for that given variable:
- `number` means your variable must be numeric, meaning it can be something like `1` or `004` or even `6e+2`.
- `array` means your variable must be a valid JSON array, like `["foo", 123]`. Please note it must be **valid JSON**, meaning strings are to be double-quoted.
- `boolean` means your variable must be either `'true'` or `'false'`
- `string` means your variable must be a valid string. In practice, *any value will pass this test*, because .env variables are always strings.
💡*You can put comments in your env template by using `#`. Great for annotations or sharing default values!*
### Usage
To run the test, simply import the main function, and pass it your `.env.template` file path. It returns a Promise that will resolve to a `ValidatorResult`.
```ts
import validateEnv from '@efstajas/validate-env'
validateEnv('./path/to/your/.env.template').then((r) => {
if (r.result === 'pass') {
// Your .env is valid!
}
if (r.result === 'fail') {
// Something is wrong in your .env
}
}).catch((e) => {
/*
Something went wrong while validating —
maybe we couldn't open the file, or the
template itself is invalid.
*/
console.error(e)
})
```
The `ValidatorResult` contains either a `SuccessPayload` like `{ result: 'pass' }`, or a `FailedPayload` which includes more info about what exactly failed:
```ts
validateEnv('./path/to/your/.env.template').then((r) => {
if (r.result === 'fail') {
const { failedVar } = r
const {
name,
expectedType
} = failedVar
switch (failedVar.reason) {
case 'MISSING':
// Variable is missing from .env
case 'WRONG_TYPE':
// Variable is present, but doesn't match expected type
}
}
})
```
### Normal usage: Validating .env before starting your app
Usually, you would want to validate your `.env` at the very beginning of your app, and if it fails, don't even initialize it. The best way to achieve this is to just wrap your initialization routine into a function, and then call it only if the `validateEnv` result indicates that your `.env` is valid. For an express application, it could look something like this:
```ts
// Use dotenv to load .env file into process.env
import * as dotenv from 'dotenv'
dotenv.config()
import express from 'express'
import validateEnv from '@efstajas/validate-env'
const initializeApplication = () => {
const server = express.server
// Register routes, middleware etc.
server.listen(8000)
}
validateEnv('./.env.template').then((r) => {
if (r.result === 'pass') {
initializeApplication()
}
})
```
### Silent mode
By default, `validate-env` prints warnings or a success message to the console automatically after validation. If you want to handle logs by yourself, you can disable this behavior by passing the `silent` option:
```ts
validateEnv('./.env.template', { silent: true }).then((r) => {
if (r.result === 'fail') {
const { failedVar } = r
const {
name,
expectedType
} = failedVar
switch (failedVar.reason) {
case 'MISSING':
console.log(`Variable ${name} is missing in .env. Expected type: ${expectedType}`)
break
case 'WRONG_TYPE':
console.log(`Variable ${name} isn't of expected type ${expectedType}.`)
break
}
return
}
console.log('.env is valid 🎉')
initializeApplication()
}
})
```