EnvSync is an attempt to make it easier for developers to initialize an
environment or update environment variables with on a single source of truth.
EnvSync currently works with Google Cloud Platform (Secrets Manager). It reads
the environment configuration from an .env.example file that is commonly used
to help developers get started with a new project, fetches the values from the
Google Cloud Platform (Secrets Manager) and intelligently merges them with your
existing .env file.
Merge Behavior: When you run envsync, it will:
- Update keys from
.env.examplein your existing.envfile - Preserve any custom keys in
.envthat aren't in.env.example - Create a new
.envfile if one doesn't exist
For example, if you have the following .env.example file:
GCP_PROJECT=myproject-dev
API_URL=http://localhost:3000
AUTH0_CLIENT_SECRET=envsync//auth0-api-client-secret/latestWill write the following .env file:
GCP_PROJECT=myproject-dev
API_URL=http://localhost:3000
AUTH0_CLIENT_SECRET=secret-value-from-gcp-projectImportant: The first variable in the example should be GCP_PROJECT as
we're using that to determine the right project. A keyfile.json
(Create and manage service account keys)
is required in the same folder as the .env.example file.
npm install @zentered/envsync
# pnpm i @zentered/envsync
# yarn add @zentered/envsync- An
.env.examplefile (useenvsync//[variable]to indicate a variable that should be fetched from Secrets Manager). The first variable should beGCP_PROJECTwith the valid project id - a
keyfile.jsonfrom a Google Cloud Platform service account with Secrets Manager API enabled, and permission to read secrets
EnvSync is a CLI tool. You can run it with npx envsync or add it as a
script in package.json:
{
"scripts": {
"envsync": "envsync"
}
}Note: this is an anti-pattern and should be avoided. Environment variables belong in the environment, not in the codebase. See 12 factor app.
- If you have multiple
.envfiles, you can provide the filename as an argument. The.envexample file must end in.example - Usage:
npx envsync .env.development.examplewill create.env.development
Note: apps that read the generated .env with util.parseEnv or --env-file
should run Node 22.16 or later, or Node 24 or later. Older parsers can read
multi-line values differently.
Values with spaces or shell characters are written in single quotes so the file
is safe to source in a shell. Node and dotenv strip the quotes. Other
--env-file readers, for example docker run --env-file, may keep them.
See CONTRIBUTING.
See LICENSE.