https://github.com/kriasoft/envars
Load environment variables securely from .env files, with seamless integration for Google Secret Manager to handle referenced secrets.
https://github.com/kriasoft/envars
aes-gcm config configuration dotenv env environment environment-variables nodejs passphrase password secret secret-management secrets secrets-manager settings vite
Last synced: about 1 year ago
JSON representation
Load environment variables securely from .env files, with seamless integration for Google Secret Manager to handle referenced secrets.
- Host: GitHub
- URL: https://github.com/kriasoft/envars
- Owner: kriasoft
- License: mit
- Created: 2021-04-30T11:14:38.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-12-21T10:43:21.000Z (over 1 year ago)
- Last Synced: 2025-06-12T10:23:32.860Z (about 1 year ago)
- Topics: aes-gcm, config, configuration, dotenv, env, environment, environment-variables, nodejs, passphrase, password, secret, secret-management, secrets, secrets-manager, settings, vite
- Language: JavaScript
- Homepage:
- Size: 6.72 MB
- Stars: 11
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# `envars` — environment variables loader
[](https://www.npmjs.com/package/envars)
[](https://www.npmjs.com/package/envars)
[](http://patreon.com/koistya)
[](https://discord.gg/bSsv7XM)
Loads environment variables for the target environment from `.env` files using [dotenv](https://github.com/motdotla/dotenv); supports cloud secret providers such as [Google Secret Manager](https://cloud.google.com/secret-manager).
By default it attempts to load `.env` files from the current working directory using the following naming convention ([learn more](https://vitejs.dev/guide/env-and-mode.html#env-files)):
```bash
.env..local # Local overrides for
.env. # 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
```bash
# with NPM
$ npm install envars --save-dev
# with Yarn
$ yarn add envars --dev
```
## Usage
```dotenv
# .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
```
```ts
// 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(),
});
```
```ts
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:
```ts
import { cleanEnv, str } from "envalid";
export default cleanEnv(process.env, {
GOOGLE_CLOUD_PROJECT: str(),
DB_PASSWORD: str(),
});
```
Or, another example using Zod:
```ts
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..local",
".env.",
".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
```ts
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](https://github.com/kriasoft/react-starter-kit) — front-end boilerplate (TypeScript, React, Material UI, Vite)
- [Full-stack Starter Kit](https://github.com/kriasoft/relay-starter-kit) — monorepo boilerplate (TypeScript, Vite, GraphQL.js, React, and Relay)
## How to Contribute
Please [fork the repo](https://github.com/kriasoft/envars/fork), create a [PR](https://docs.github.com/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request), or send me a message on [Discord](https://discord.gg/bSsv7XM) (`@koistya`).
```bash
$ git clone https://github.com//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](https://github.com/kriasoft/envars/blob/main/LICENSE) file.
---
Made with ♥ by Konstantin Tarkus ([@koistya](https://twitter.com/koistya), [blog](https://medium.com/@koistya))
and [contributors](https://github.com/kriasoft/envars/graphs/contributors).