@creatrip/env-safe

env-safe is module that loads environment variables from a .env file into process.env with type-safe. And can also validate the type of process.env. env-safe is dependent on dotenv and reflect-metadata.

Note: env-safe is not 1.0 yet. Be prepared to do major refactoring due to breaking API changes.

Install

npm install @creatrip/env-safe --save

Or installing with yarn? yarn add @creatrip/env-safe

Usage

Turn on emitDecoratorMetadata, experimentalDecorators in tsconfig.json:

{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true
    ...
  }
  ...
}

Create a .env file in the root of your project:

DATABASE_HOST="localhost"
DATABASE_PORT=3306

Use env-safe to create env config class:

import { EnvSafe, EnvKey } from "@creatrip/env-safe";

@EnvSafe()
export class Env {
  @EnvKey()
  static DATABASE_HOST: string;

  @EnvKey()
  static DATABASE_PORT: number;
}

filename: env.ts

That's it. Just use the newly created config class:

import { Env } from "./env.ts";

mysql.connect({
  host: Env.DATABASE_HOST, // String("localhost")
  port: Env.DATABASE_PORT, // Number(3306)
});

Documentation

Comment

Comments may be added to your file on their own line or inline:

# This is a comment
DATABASE_HOST="localhost" # comment
DATABASE_PASSWORD="can-define-with-#"

Comments begin where a # exists, so if your value contains a # please wrap it in quotes.

Default value

Set default value to env config class property:

@EnvSafe()
export class Env {
  @EnvKey({ default: "localhost" })
  static DATABASE_HOST: string;

  @EnvKey({ default: 3306 })
  static DATABASE_PORT: number;
}

Nullable

Set nullable to env config class property:

@EnvSafe()
export class Env {
  @EnvKey({ nullable: true })
  static DATABASE_HOST: string | null; // String or null
}

Type-Safe

Since the provided .env does not contain all the variables defined in env config class, an exception is thrown:

DATABASE_HOST=
DATABASE_PORT="wrong data"

@EnvSafe()
export class Env {
  @EnvKey()
  static DATABASE_HOST: string; // Not defined Error

  @EnvKey()
  static DATABASE_PORT: number; // NaN Error

  @EnvKey()
  static DATABASE_USER: string; // Not defined Error
}

$ node dist/index.js

ERROR: .env - DATABASE_HOST is not defined
ERROR: .env - DATABASE_PORT is not allowed
ERROR: .env - DATABASE_USER is not defined

Change .env path

Can change .env path in your project:

$ ls
development.env  stagging.env  production.env

@EnvSafe({ path: 'development.env' })
export class Env {
  ...
}

Multiple env config class

Can define multiple env config class:

AWS_SECRET_KEY="secret key"
S3_BUCKET="bucket name"

@EnvSafe()
export class EnvAWS {
  @EnvKey()
  static AWS_SECRET_KEY: string; // String("secret key")
}

@EnvSafe()
export class EnvS3 {
  @EnvKey()
  static S3_BUCKET: string; // String("bucket name")
}

Auto generate template .env

If you don't make .env, just run application. .env will automatically generated by env class:

https://user-images.githubusercontent.com/25793226/205256885-1ba27e5d-ec98-4c9a-95be-418a81c28138.mov

Samples

Take a look at the samples in sample for examples of usage.

Contributing

Learn about contribution here and how to setup your development environment here.

License

env-safe is MIT Licensed.