Migrate from dotenv

Why migrate from dotenv?

Validation: Catch misconfigurations early with schema-driven validation.
Security: Redact secrets and prevent accidental leaks.
Type-safety: Generate types automatically for your config.
External secrets: Load secrets from providers like 1Password, AWS, and more.

Migrating from dotenvx CLI

If you use dotenvx via the CLI, you can switch to varlock run:

# Before (dotenv CLI)
dotenvx run -- node app.js

# env specific
dotenvx run -f .env.staging -- node app.js

# install varlock
brew install dmno-dev/tap/varlock

# After (varlock CLI)
varlock run -- node app.js

# To specify an environment, set your env flag (see your .env.schema)
APP_ENV=staging varlock run -- node app.js

You can use multiple .env files (see Environments guide).

Migrating from dotenv npm package

Initialize your project with varlock init to install varlock and generate a .env.schema from any existing .env files.

npx varlock init

yarn dlx varlock init

pnpm dlx varlock init

Then to use varlock in your code, you can replace dotenv/config with varlock/auto-load:

// Before (dotenv)
 import 'dotenv/config';
 import 'varlock/auto-load';

Finally, you can remove dotenv from your dependencies:

npm uninstall dotenv

yarn remove dotenv

pnpm remove dotenv

Using overrides

If dotenv is being used under the hood of one of your dependencies, you can use overrides to seamlessly swap in varlock instead.

See NPM overrides docs

{
  "overrides": {
    "dotenv": "varlock"
  }
}

See yarn resolutions docs

{
  "resolutions": {
    "**/dotenv": "npm:varlock"
  },
}

In a monorepo, this override must be done in the monorepo’s root package.json file!

pnpm version 10+
pnpm version 9

See pnpm v10 overrides docs

overrides:
  "dotenv": "npm:varlock"

This must be set in pnpm-workspace.yaml, which lives at the root of your repo, regardless of whether you are using a monorepo or not.

pnpm version 9

See pnpm v9 overrides docs

{
  "pnpm": {
    "overrides": {
      "dotenv": "npm:varlock"
    }
  }
}