envars — environment variables loader

Loads environment variables for the target environment from .env files using dotenv; supports cloud secret providers such as Google Secret Manager.

By default it attempts to load .env files from the current working directory using the following naming convention (learn more):

.env.<environment>.local     # Local overrides for <environment>
.env.<environment>           # Environment-specific settings
.env.local                   # Local overrides
.env                         # Default settings

Created and diligently upheld with the generous backing of these exceptional companies:

How to Install

# with NPM
$ npm install envars --save-dev

# with Yarn
$ yarn add envars --dev

Usage

# .env
# Environment variables for the local development environment
# NOTE: Secret values need to follow this format:
#       secret://[provider]/[resource]
GOOGLE_CLOUD_PROJECT=example
DB_PASSWORD=secret://google/projects/example/secrets/db-password/latest

// core/env.ts
import { cleanEnv, str } from "envalid";

/**
 * Sanitized and validated environment variables.
 * @see https://github.com/af/envalid#readme
 */
export default cleanEnv(process.env, {
  GOOGLE_CLOUD_PROJECT: str(),
  DB_PASSWORD: str(),
});

import { loadEnv } from "envars";

const [env] = await loadEnv("production", {
  root: ".",
  schema: "./core/env.ts",
  mergeTo: process.env,
});

API

loadEnv(mode?, options?)

mode

Type: string (optional) Default: undefined Example: production, development, staging, etc.

options

Type: object (optional)

root

Type: string (optional) Default: . (current working directory).

The root directory where it looks for .env files.

schema

Type: string (optional) Default: undefined Example: ./core/env.ts

The path to the TypeScript or JavaScript module exporting a sanitized environment object. Example:

import { cleanEnv, str } from "envalid";

export default cleanEnv(process.env, {
  GOOGLE_CLOUD_PROJECT: str(),
  DB_PASSWORD: str(),
});

Or, another example using Zod:

import { z } from "zod";

export const env = z
  .object({
    GOOGLE_CLOUD_PROJECT: z.string(),
    DB_PASSWORD: z.string(),
  })
  .parse(process.env);

files

Type: string[] (optional) Default: [ ".env.<environment>.local", ".env.<environment>", ".env.local", ".env" ]

The list of file patterns where to look for .env files.

mergeTo

Type: object (optional) Default: undefined Example: process.env

The object where to merge the loaded environment variables.

Usage with Vite

import { defineConfig } from "vite";
import { loadEnv } from "envars";

export default defineConfig(async ({ mode }) => {
  const [env] = await loadEnv(mode, {
    root: "../",
    schema: "./core/env.ts",
    mergeTo: process.env,
  });

  return {
    build: {
      ssr: "index.ts",
      target: "esnext",
      sourcemap: true,
    },
  };
});

References

• https://cloud.google.com/secret-manager/docs

Backers 💰

Related Projects

• React Starter Kit — front-end boilerplate (TypeScript, React, Material UI, Vite)
• Full-stack Starter Kit — monorepo boilerplate (TypeScript, Vite, GraphQL.js, React, and Relay)

How to Contribute

Please fork the repo, create a PR, or send me a message on Discord (@koistya).

$ git clone https://github.com/<username>/envars.git
$ cd ./envars
$ corepack enable
$ yarn test

License

Copyright © 2021-present Kriasoft. This source code is licensed under the MIT license found in the LICENSE file.

Made with ♥ by Konstantin Tarkus (@koistya, blog) and contributors.