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):

1.env.<environment>.local     # Local overrides for <environment>
2.env.<environment>           # Environment-specific settings
3.env.local                   # Local overrides
4.env                         # Default settings

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

    

How to Install

1# with NPM
2$ npm install envars --save-dev
3
4# with Yarn
5$ yarn add envars --dev

Usage

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

1// core/env.ts
2import { cleanEnv, str } from "envalid";
3
4/**
5 * Sanitized and validated environment variables.
6 * @see https://github.com/af/envalid#readme
7 */
8export default cleanEnv(process.env, {
9  GOOGLE_CLOUD_PROJECT: str(),
10  DB_PASSWORD: str(),
11});

1import { loadEnv } from "envars";
2
3const [env] = await loadEnv("production", {
4  root: ".",
5  schema: "./core/env.ts",
6  mergeTo: process.env,
7});

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:

1import { cleanEnv, str } from "envalid";
2
3export default cleanEnv(process.env, {
4  GOOGLE_CLOUD_PROJECT: str(),
5  DB_PASSWORD: str(),
6});

Or, another example using Zod:

1import { z } from "zod";
2
3export const env = z
4  .object({
5    GOOGLE_CLOUD_PROJECT: z.string(),
6    DB_PASSWORD: z.string(),
7  })
8  .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

1import { defineConfig } from "vite";
2import { loadEnv } from "envars";
3
4export default defineConfig(async ({ mode }) => {
5  const [env] = await loadEnv(mode, {
6    root: "../",
7    schema: "./core/env.ts",
8    mergeTo: process.env,
9  });
10
11  return {
12    build: {
13      ssr: "index.ts",
14      target: "esnext",
15      sourcemap: true,
16    },
17  };
18});

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).

1$ git clone https://github.com/<username>/envars.git
2$ cd ./envars
3$ corepack enable
4$ 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.}