envars — environment variables loader

Loads environment variables for the target environment from .env files using dotenv. Also supports cloud secret providers such as Google Secret Manager, AWS Secrets Manager, and (experimental) Azure Key Vault. Now you can keep your secrets secret, even from yourself.

Features

• Loads .env files using Vite-style conventions
• Supports secret references from Google, AWS, and Azure
• TypeScript and monorepo friendly
• Works with Vite, Node.js, and serverless deployments
• Simple API, zero-config for most use cases

Why envars?

• Unified config: Manage local and cloud secrets with a single API.
• Predictable: Follows conventions from Vite and modern Node.js tooling.
• Flexible: Works in monorepos, serverless, and traditional deployments.
• Type-safe: Integrates with envalid, Zod, and other schema validators.

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

Quick Start

import { loadEnv } from "envars";

const [env] = await loadEnv("development");
console.log(env);

Advanced 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
• https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html
• https://learn.microsoft.com/en-us/azure/key-vault/secrets/

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)

Community & Support

• 💬 Join our Discord for questions, help, and discussion (or just to show off your best .env puns)
• 🐞 Report issues or request features on GitHub
• 🙏 Sponsor development to support ongoing maintenance (we promise not to spend it all on coffee)

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.

---

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