No, way.

Yes. Yes, way.

Dotenv's fast mode now beats Node's native parser on all current LTS versions - Node 22 and 24 - across Linux and Windows in our benchmarks. See below where Node native is still faster.

Background

Five months ago, the wildest PR ever landed in dotenv. Dotenv contributions are typically small parser changes, type detail additions, or proposals for all new features. This was something different.

This was a new parser, claiming 2x speedup.

Some guy from Sweden, homanp. A character scanning approach. Pretty sick, tbh.

So what did I do? What any maintainer does for a package depended on by tens of millions. I sat on it. lol.

But we also got in touch with each other and had a chat. He and his cofounder ran a service called Superagent.sh - securing PRs. They generously offered to secure Dotenvx's, and today they do that for all kinds of open source projects - even Firecrawl.

The Release

Back to Dotenv. The parser was contributed as a full replacement. That's too risky so we put it behind the --fast flag. On September 17th, five months after that initial PR dropped, we released it.

It's fast.

Source: GitHub Actions benchmarks, September 23, 2026.

Since then the community is using it, have found edge cases, and those have been patched. It's cool to see, and I won't be surprised if it becomes adopted by other dotenv implementations.

Usage

With dotenv 18 or later, enable fast mode in your app:

require('dotenv').config({ fast: true })

Or use the new CLI:

$ npx dotenv run --fast -- node index.js

Dotenv fast mode in action.

The Future

Software is changing, fast. With Dotenv we're committed to maintaining the past while still evolving .env. This --fast parser is an example of that.

If you love .env and also want to see it evolve, please support us. Use dotenv, use dotenvx, and even snag a dotenv membership. Be part of the .env story. It's not all written yet.

Lastly, a giant thank you to Superagent.sh for bringing this to the dotenv community.

superagent_

A lot is changing about how we write code. Agents do more of the typing. But editing a .env file is still something many of us do ourselves: paste in an API key, change a database URL, or add a variable for a new service.

That puts secrets right on your screen. Open the wrong tab during a screen share and they're there for everyone to see.

The extension's job is simple: keep secrets out of sight while you work in your editor. Reveal them when you need them, then get back to work. That's the focus of 1.0 and the releases that followed.

Open your .env without the flash

Auto-cloaking has been part of the extension for years. But a limitation of VS Code's native editor meant secrets could briefly flash before the extension could mask them when opening a file or switching tabs.

For 1.0, we worked around that limitation by building our own Dotenv Editor. It masks values before the editor becomes visible. Open your .env and the names are readable, while the values stay hidden.

Click Toggle auto-cloaking to reveal or hide values. Switching tabs hides them again. Editing, find and replace, multiple cursors, undo, and redo still work. Cloaking only changes what you see; copying a value copies its actual text.

We've also added cloaking for Docker Compose environment values. YAML uses the native editor, so it doesn't have the same no-flash behavior as the Dotenv Editor.

Complete names. Reveal when needed.

Start typing process.env. and choose a variable from your dotenv files. Suggestions show the source filenames and keep values masked.

Already have a variable in your code? Hover over it to see its source, then use Reveal value or Hide value in the popup.

The latest releases add support for import { env } from 'node:process', including aliases, plus Julia, Erlang, Swift, and Clojure. Nested dotenv files are discovered too, with lookups scoped to the source file's directory and its parents up to the workspace root.

Still your .env file

You can keep working with the .env files you already have. Syntax highlighting keeps names, values, comments, and quoted strings easy to read. The new editor also highlights numeric values.

Encrypted files, too

If you use dotenvx encryption, the latest releases also let you hover over an encrypted: value and click Decrypt value. The file stays encrypted, and the displayed plaintext clears when you hide it, leave the popup, or switch tabs.

This feature needs the dotenvx CLI installed locally, a saved file in a trusted workspace, and the matching private key available locally. You don't need encryption or the CLI to use the extension's cloaking, completion, and syntax highlighting.

Try it

Install or update Dotenv Official to 1.5.2 or later. You can find the full release history in the changelog.

As more of our coding moves to agents, the moments we spend editing secrets ourselves still deserve care. Dotenv for VS Code is back, past 1.0, and focused on making that everyday task a little safer.

For years, dotenv has loaded your .env file from inside your application. Now it can load those variables before your command starts. Your app just reads its environment.

That makes the same .env file useful for scripts, tests, and other command-line tools, too. And it gives coding agents a simple way to run a command with the environment it needs.

Usage

Install dotenv@18.0.0 or greater.

$ npm install dotenv --save

Create your .env file.

# .env
HELLO="World"

Create a simple app. There's no dotenv import needed here.

// index.js
console.log(`Hello ${process.env.HELLO}`)

Run it with the new CLI.

$ npx dotenv run -- node index.js
◇ injected env (1) from .env
Hello World

That's it. Dotenv loads .env, then starts Node with those variables available. The command after the -- can be any executable available on your PATH.

Choose your environment

By default, the CLI reads .env. To use another file, pass -f:

$ npx dotenv run -f .env.local -- node index.js

Variables already set in your environment take precedence. Add --override if you want the file's values to win instead.

Upgrading

The familiar require('dotenv').config() API is still here. If you used Node's -r dotenv/config preload, switch to the CLI command above. Version 18 also removes the legacy .env.vault format; use dotenvx for encrypted .env files.

There's an optional faster parser, too: add --fast to your CLI command to try it. See the release notes for the full changes.

A small command, a big step

Dotenv started with a simple idea: load your .env file and get to work. The CLI brings that same simplicity to any command - whether you run it yourself or an agent runs it for you. A small command, and a big next step for dotenv.

This post originally appeared on dev.to.

Most teams keep local secrets in .env.local and add that file to .gitignore. That is the bare minimum, and it does not address a more pressing risk: supply chain attacks and compromised local tooling that read .env files as soon as they get repo access.

Once a malicious dependency, postinstall script, editor extension, MCP server, AI coding tool, or other local helper can inspect your workspace, plain-text .env.local files become low-effort, high-value targets.

I wanted a low-friction way to reduce that blast radius without forcing the whole team onto a heavyweight secrets manager for day-to-day local development.

This is the pattern I landed on:

• keep non-secret local config in .env.local
• move actual secrets into .env.local.secrets
• encrypt .env.local.secrets with dotenvx
• move the decryption key out of disk and into macOS Keychain
• load .env.local first, then only decrypt secrets when an explicit opt-in flag says to

Important distinction: I am not using dotenvx the way it is often marketed, where encrypted env files are committed to the repo and shared that way. This setup is local-only. The encrypted file and .env.keys both stay uncommitted, and I prefer it that way. Committing encrypted env files is useful when you want team-wide encrypted config distribution, but that was not my goal. I wanted to reduce plaintext secrets on developer machines and raise the cost of tools that slurp local env files, while keeping the workflow simple enough that teammates actually use it.

The setup

Start with a normal .env.local, then split it:

• .env.local: safe local config, feature flags, non-secret defaults
• .env.local.secrets: secrets only

Example:

# .env.local
BETTER_AUTH_URL=http://localhost:3000
USE_KEYCHAIN_FOR_DOTX=true

# .env.local.secrets
POSTGRES_URL=postgres://...
GOOGLE_CLIENT_SECRET=...
BETTER_AUTH_SECRET=...

Make sure your .gitignore covers all the pieces:

.env.local
.env.local.secrets
.env.keys

Then encrypt the secrets file:

pnpm exec dotenvx encrypt -f .env.local.secrets

That gives you an encrypted .env.local.secrets and a decryption key in .env.keys.

At this point, you have improved at-rest security a bit, but the key is still on disk, which is not the end state we want.

Why bother with the extra steps?

There have been enough supply chain and developer tooling incidents lately that I no longer treat "it is gitignored" as a meaningful security boundary. Once something malicious lands in your development environment, one of the first profitable things it can do is read local env files and exfiltrate credentials.

Encrypting local secrets at rest is not a complete defense, but it is a useful speed bump:

• secrets are no longer sitting in plaintext on disk
• the decryption key can live in the OS keychain instead of another dotfile
• accidental repo-wide file reads become less damaging
• you can keep the workflow mostly compatible with existing frameworks

This does not protect secrets after your app starts. At runtime, the process still has decrypted environment variables in memory. But that is still better than leaving everything plaintext on disk all the time.

Move the key into macOS Keychain

Copy the DOTENV_PRIVATE_KEY_LOCAL_SECRETS value from .env.keys, then store it in Keychain:

security add-generic-password -U \
  -a LOCAL_SECRETS_DOTENVX_KEY \
  -s LOCAL_SECRETS_DOTENVX_KEY \
  -w

With security, keeping -w as the last argument makes it prompt you for the secret instead of putting it in your shell history.

The LOCAL_SECRETS_DOTENVX_KEY label is just an example. Pick any consistent Keychain item name you want, then use that same name everywhere in your scripts.

Now you can delete .env.keys. Before you do, stash the key somewhere safe outside the repo. A password manager like 1Password is a good choice. You will need it if you set up another machine or need to recover.

With that, your decryption key is no longer sitting next to the repo in another plaintext file.

Linux and Windows. This post uses macOS Keychain, but the same idea applies elsewhere. On Linux, secret-tool (backed by libsecret and GNOME Keyring or KWallet) fills the same role. On Windows, you can use Credential Manager via PowerShell's Get-StoredCredential / New-StoredCredential cmdlets. The loading pattern stays the same; only the key retrieval command changes.

The loading pattern

The subtle part is loader order.

If you want a flag like USE_KEYCHAIN_FOR_DOTX=true to live in .env.local, your app needs to read .env.local before it decides whether to pull the decryption key from Keychain.

That means the loader should do this:

1. Load .env
2. Load .env.local
3. Check USE_KEYCHAIN_FOR_DOTX
4. If enabled, read DOTENV_PRIVATE_KEY_LOCAL_SECRETS from Keychain
5. Load .env.local.secrets

Here is the core idea in TypeScript:

Open as GitHub Gist

import { execFileSync } from "node:child_process";
import { existsSync } from "node:fs";
import { resolve } from "node:path";
import { config } from "@dotenvx/dotenvx";

export function loadEnv(): void {
  for (const file of [".env", ".env.local"]) {
    const path = resolve(process.cwd(), file);
    if (existsSync(path)) {
      config({ path });
    }
  }

  const localSecretsPath = resolve(process.cwd(), ".env.local.secrets");
  if (!existsSync(localSecretsPath)) {
    return;
  }

  if (process.env.USE_KEYCHAIN_FOR_DOTX === "true") {
    try {
      process.env.DOTENV_PRIVATE_KEY_LOCAL_SECRETS = execFileSync(
        "security",
        [
          "find-generic-password",
          "-a",
          "LOCAL_SECRETS_DOTENVX_KEY",
          "-s",
          "LOCAL_SECRETS_DOTENVX_KEY",
          "-w",
        ],
        { encoding: "utf-8" },
      ).trim();
    } catch (err) {
      throw new Error(
        "Failed to read decryption key from macOS Keychain. " +
          "Make sure the LOCAL_SECRETS_DOTENVX_KEY item exists. " +
          "See scripts/store-keychain-key.sh for setup.",
        { cause: err },
      );
    }
  }

  config({ path: localSecretsPath, overload: true });

  // The private key has done its job. Remove it from the environment so it
  // is not visible in process.env dumps or child process inheritance.
  delete process.env.DOTENV_PRIVATE_KEY_LOCAL_SECRETS;
}

Three notes:

• execFileSync will throw on a non-zero exit, so the try/catch above turns a cryptic child-process error into a clear setup instruction
• the delete at the end matters: once dotenvx has decrypted the secrets into their individual env vars, the private key has no further purpose; leaving it in process.env means any code that inspects the environment (logging, diagnostics, error reporters) could leak the one key that decrypts the file
• do not log even partial key material during startup. That is easy to get wrong when debugging the integration

One thing this does not protect against: once your app is running, the decrypted secrets are plain strings in process.env. Anyone who can attach a Node debugger to your process can inspect memory directly.

Cross-process env snooping is more nuanced. On macOS 11+, SIP prevents processes from reading other processes' environment variables, so this vector is largely closed on a default macOS install. On Linux, /proc/<pid>/environ is still readable by any process running as the same user. Either way, this pattern is about secrets at rest on disk, not secrets in a running process.

Next.js integration

Update: For the standard Next.js setup, including deployments on Vercel, use the canonical @dotenvx/next-env guide. The custom instrumentation below belongs to this article's local macOS Keychain workflow; it is not the recommended general Next.js integration or a Vercel deployment recipe.

If you are using Next.js, you cannot just call loadEnv() from anywhere and expect it to work. Next.js has its own env loading built in, and by the time your application code runs, it has already resolved which variables are available.

The right place to hook this in is instrumentation.ts (or .js). Next.js calls the register function exported from this file once when the server starts, before any routes or middleware run. That makes it the earliest reliable point to pull secrets from Keychain and inject them into process.env.

// instrumentation.ts
export async function register() {
  const { loadEnv } = await import("./lib/load-env");
  loadEnv();
}

The dynamic import is intentional. It keeps the Keychain and dotenvx logic out of the client bundle and avoids top-level side effects that could run at the wrong time.

Make sure instrumentation.ts is at your project root (next to next.config), and that you are on Next.js 15+ where the instrumentation hook is stable. On older versions (13.2 through 14.x) it works but requires setting experimental.instrumentationHook: true in your Next config.

Helper scripts for temporary decrypt/re-encrypt

I also like keeping two tiny helper scripts around so I can temporarily decrypt the file, edit it, and then re-encrypt it.

#!/usr/bin/env bash
# scripts/decrypt-local-secrets.sh
set -euo pipefail

KEYCHAIN_ITEM_NAME="LOCAL_SECRETS_DOTENVX_KEY"

export DOTENV_PRIVATE_KEY_LOCAL_SECRETS="$(
  security find-generic-password \
    -a "$KEYCHAIN_ITEM_NAME" \
    -s "$KEYCHAIN_ITEM_NAME" \
    -w
)"

pnpm exec dotenvx decrypt -f .env.local.secrets

#!/usr/bin/env bash
# scripts/encrypt-local-secrets.sh
set -euo pipefail

KEYCHAIN_ITEM_NAME="LOCAL_SECRETS_DOTENVX_KEY"

export DOTENV_PRIVATE_KEY_LOCAL_SECRETS="$(
  security find-generic-password \
    -a "$KEYCHAIN_ITEM_NAME" \
    -s "$KEYCHAIN_ITEM_NAME" \
    -w
)"

pnpm exec dotenvx encrypt -f .env.local.secrets

That gives you a simple workflow:

bash scripts/decrypt-local-secrets.sh
# edit .env.local.secrets
bash scripts/encrypt-local-secrets.sh

One risk here: if you decrypt the file, edit it, and forget to re-encrypt, your secrets are back to sitting in plaintext. A git pre-commit hook can catch this. Something like:

#!/usr/bin/env bash
# .husky/pre-commit or .git/hooks/pre-commit
if head -c 50 .env.local.secrets 2>/dev/null | grep -qv "^#/"; then
  echo "ERROR: .env.local.secrets appears to be decrypted. Run:"
  echo "  bash scripts/encrypt-local-secrets.sh"
  exit 1
fi

(dotenvx-encrypted files start with a comment header like #/-------------------[DOTENV]--------------------/, so checking for the absence of that prefix is a reasonable heuristic.)

Where this helps, and where it doesn't

This pattern helps with:

• raising the cost of supply chain attacks that look for .env files
• repo-wide local file scraping
• accidental plaintext secret exposure in local tooling
• reducing how many places secrets live on disk
• avoiding accidental exposure during screen sharing and pair programming

It does not solve:

• malicious code running inside your process
• a debugger attached to your Node process (secrets are in memory as plain strings)
• cross-process env snooping on Linux (/proc/<pid>/environ); macOS SIP blocks this since Big Sur, but Linux does not
• secrets already exported into your shell
• logs or copy/paste leaks
• production secret management

Think of it as one useful layer, not as a silver bullet.

A note on screen sharing

If your secrets live in a plain-text .env.local, it is very easy to accidentally flash them on screen during a Zoom call, a pair programming session, or a live demo. All it takes is opening the wrong file, running cat on it, or having your editor preview it in a sidebar.

With encrypted .env.local.secrets, that file is just opaque ciphertext. Even if you open it on camera, nobody sees your database credentials or API keys. The decryption only happens at runtime, in memory, when your app starts, not when a human or a screen recording is looking at your filesystem.

This is not a reason to adopt the pattern on its own, but it is a nice side effect that has already saved me at least once.

The developer-experience bar matters

The reason I like this approach is that it is security work people may actually keep using.

Once set up, the workflow is close to normal local development:

• keep config in .env.local
• keep secrets in .env.local.secrets
• let the app pull the key from Keychain when needed

That is much more likely to stick than a system that feels "more secure" on paper but creates enough friction that everyone bypasses it.

If you want to adopt this

My suggestions:

1. Start with local-only encryption, not a big secret-sharing redesign.
2. Separate non-secret config from secrets first.
3. Make the Keychain path opt-in with a clear env flag.
4. Ensure .env.local loads before you evaluate that flag.
5. Audit helper scripts too, not just the main app boot path.
6. Back up your decryption key in a password manager before deleting .env.keys.
7. Add a pre-commit hook to catch unencrypted secrets files.
8. Never print keys, even partially, while debugging the integration.

That last point deserves repeating.

Security improvements have a way of being partially undone by "temporary" debugging statements.

Related tools worth looking at

If this pattern feels too lightweight for your needs, or you want something more structured, there are good adjacent tools in this space.

SOPS is a strong option when you want encrypted files as a first-class workflow, especially in teams already comfortable with cloud KMS, age, or GitOps-style config management.

DMNO goes in a different direction: schema-aware config, tooling around developer experience, and integrations with external secret stores. Their 1Password plugin is a good example if you want local development ergonomics tied more directly to a secrets manager instead of local encrypted .env files.

I do not see these as mutually exclusive with the smaller pattern in this post. They just sit at different points on the complexity and capability curve.

Closing thought

I do not think local .env files are going away anytime soon.

But I do think the threat model around them has changed.

A small amount of structure, encryption at rest, and OS-managed key storage can go a surprisingly long way without making local development miserable.

Followup: I also wrote a companion script that scans your machine for plaintext secrets sitting in .env files. It pairs well with this post as a way to find what needs encrypting. Find Plaintext Secrets Hiding in Your .env Files

It catches .env* key drift in pull requests and leaves a review comment with concrete fixes.

It uses Warp's Oz under the hood to do the review, and it works great.

Why

Teams with multiple env files (.env, .env.production, .env.staging, etc) slowly drift.

Someone adds TWILIO_API_KEY to one file and forgets the others. CI passes, deploy goes out, and then something breaks in preview or prod.

Wizard of Drift catches that in the PR before merge.

The Real Problem

Most env drift bugs are boring and expensive:

• local works, preview fails
• preview works, production fails
• one service has a key, another service does not

And they are hard to catch in code review because reviewers are focused on app code, not checking every .env* file by hand.

Even worse, the PR diff can hide this. If a new key is added in .env.production only, nobody notices until a runtime path hits missing config.

This is the kind of failure that burns hours for no good reason.

What It Checks

• Scans .env* files in the repo
• Excludes .env.keys (never commit that)
• Compares key names only (not values)
• Handles DOTENV_PUBLIC_KEY naming rules per file:
  • .env expects DOTENV_PUBLIC_KEY
  • .env.<target> expects DOTENV_PUBLIC_KEY_<TARGET_UPPERCASE>
• Posts a PR review summary with missing key lines to add

Add It In 30 Seconds

name: Env Drift Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  env-drift:
    runs-on: ubuntu-latest
    steps:
      - uses: dotenvx/wizard-of-drift@v1
        with:
          warp_api_key: $
          github_token: $
          warp_agent_profile: "" # optional

Why A Coding Agent Works Well Here

This is a great use case for an agent because the input is high-context but bounded:

• list of env files
• extracted key sets
• the .env* diff in the PR
• explicit rules about DOTENV_PUBLIC_KEY naming

Wizard of Drift builds that context first, then gives the agent (in this case Oz) a tight prompt and asks for one output: a concise review summary with exact keys to add.

That pattern matters.

The agent is not guessing from vague code context. It is reviewing a purpose-built context document generated by CI, then returning actionable output directly into the PR conversation.

So the reviewer sees concrete fixes, not generic AI advice.

The Bigger Idea

This is the kind of workflow I want more of:

• static CI context
• AI agent review
• deterministic output in PR comments

And Oz was a great choice here because I wanted to easily trigger a coding agent from a GitHub action. Plus it supports any model and can be monitored from its dashboard.

The combination makes my .env workflows safer and easier to operate at scale. Dotenvx gives you the secure env model and the agent gives you a practical enforcement loop at review time.

Together, they remove a class of annoying config breakages before they merge.

⚠️ Use the new Next.js approach

This article's original setup has been superseded. Use @dotenvx/next-env for Next.js, including apps deployed on Vercel. It replaces the earlier CLI wrapper and instrumentation approach.

Follow the current Next.js setup →

By Tony Vantur

Dotenvx encrypts your .env files so you can commit them to git. Your app reads decrypted values through process.env, while the private decryption keys stay outside your repository.

Set up Next.js

Follow the canonical Next.js guide to install @dotenvx/dotenvx and @dotenvx/next-env, add the @next/env override, and encrypt your .env file. The guide includes the current configuration and troubleshooting steps.

Use your normal Next.js scripts (next dev, next build, and next start) and continue reading variables with process.env.

Deploy on Vercel

Use the same canonical Next.js integration on Vercel. Commit encrypted environment files, keep .env.keys out of deployment uploads, and configure the matching private keys in Vercel.

Configure keys for each Vercel environment you deploy to. Preview builds also use NODE_ENV=production, so Vercel's Preview scope does not automatically select a different Next.js env file.

Migrating from the earlier instructions

After applying the canonical setup:

• Remove dotenvx run -- wrappers from your Next.js scripts.
• Remove instrumentation code added solely to call dotenvx.config(). Keep instrumentation used for other purposes.
• Replace any dotenvx.get calls introduced by the old Vercel guide with process.env reads.
• Keep your encrypted env files and configure their matching decryption keys on Vercel, then redeploy.

Resources

• Next.js guide — Canonical integration with @dotenvx/next-env
• Dotenvx documentation — CLI and SDK reference

This was a real problem for us. We publish 64 npm packages, and rotating tokens across all of them by hand was not going to be sustainable. Every expiration meant touching dozens of pipelines and praying the next publish didn't fail.

So we built a solution. Introducing Dotenvx Rotate - part of Dotenvx Armor ⛨.

How It Works

Install dotenvx-armor.

$ curl -sfS https://dotenvx.com/armor | sh

Run rotate npm connect to connect npm.

$ dotenvx-armor rotate npm connect

When prompted enter your npm username and password.

$ dotenvx-armor rotate npm connect
✔ npm username: USERNAME
✔ npm password: PASSWORD

This opens a local browser session, connecting your npm account.

IMPORTANT: Note that this is local only - this way we can bypass the need for storing your credentials.

Complete any 2FA steps manually.

On success, return to your CLI, and you will see a passcard created.

$ dotenvx-armor rotate npm connect
✔ npm username: USERNAME
✔ npm password: PASSWORD
✔ connected [https://armor.dotenvx.com/go/pas_1234..]

Dotenvx Passcards are special connectors allowing account access.

Next, use the passcard to rotate your npm token.

Rotate

Run rotate on the passcard.

$ dotenvx-armor rotate dotenvx://pas_1234..
⠏ rotating..

It takes 10-30 seconds. On success, it returns a Dotenvx Rotation Token (ROT).

$ dotenvx-armor rotate dotenvx://pas_1234..
✔ rotated [https://armor.dotenvx.com/go/pas_1234..]
⮕ next run [dotenvx-armor get dotenvx://rot_a2c4..]

Dotenvx Rotation Tokens (ROTs) are special tokens that can change value. You can think of them as proxy tokens.

Next, let's get the value for it.

Get

Run get on the rotation token.

$ dotenvx-armor get dotenvx://rot_a2c4..
npm_d2cJ..

It returns your npm token. Cool!

Rotate Again

Run rotate on the passcard again.

$ dotenvx-armor rotate dotenvx://pas_1234..
✔ rotated [https://armor.dotenvx.com/go/pas_1234..]
⮕ next run [dotenvx-armor get dotenvx://rot_a2c4..]

And get the ROT again.

$ dotenvx-armor get dotenvx://rot_a2c4..
npm_cbGY..

The value changed. Way cool!

That's the ROT at work. ROTs introduce a new key rotation primitive: the npm token rotates, the reference does not. This is useful for operations, especially CI/CD.

CI/CD

Previously, our CI/CD had npm publish with a hardcoded secrets.NPM_TOKEN:

npm:
  ...
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: '18.x'
        registry-url: 'https://registry.npmjs.org'
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Step 1

We first replaced secrets.NPM_TOKEN with env.NODE_AUTH_TOKEN.

npm:
  ...
  runs-on: ubuntu-latest
  steps:
    ...
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ env.NODE_AUTH_TOKEN }}

Step 2

Then we added a step to:

• Install dotenvx-armor
• Run dotenvx-armor get to echo its value to NODE_AUTH_TOKEN

npm:
  ...
  runs-on: ubuntu-latest
  steps:
    ...
    - run: |
        curl -sfS https://dotenvx.sh/armor | sh
        echo "NODE_AUTH_TOKEN=$(dotenvx-armor get dotenvx://rot_a2c4 --token '${{ secrets.DOTENVX_ARMOR_TOKEN }}')" >> $GITHUB_ENV
    - run: npm publish
      env:
        NODE_AUTH_TOKEN: ${{ env.NODE_AUTH_TOKEN }}

Step 3

Last, we set DOTENVX_ARMOR_TOKEN in GitHub Actions Secrets (or GitLab CI, CircleCI, or wherever you run your automated npm publishing).

Tip: Find your DOTENVX_ARMOR_TOKEN on your Dotenvx Settings Page.

On your next CI run, it will inject the latest rotated NPM token and successfully publish your npm module(s).

Incredible!

Conclusion

Publishing now works indefinitely with rotating NPM tokens, powered by a new rotation primitive (ROTs) and passcard connectors.

• NPM token leaked? Just rotate it - all your operations still work.
• Employee left who knew the old token? Rotate it - all your operations still work.
• NPM token should be rotated every N days for compliance? Put it on a schedule - all your operations still work.

This has worked really well for us. If it sounds useful, you can use it too. Sign up for Dotenvx Armor ⛨.

P.S. If you're running this at enterprise scale with compliance requirements, scheduled rotation, or broader CI/CD concerns, please get in touch. We'd like to help.

¹ Strengthening npm security: Important changes to authentication and token management

In practice, Docker Compose secrets are just plaintext files in disguise, which introduces its own risks. Meanwhile, dotenvx takes a different approach with just-in-time secret injection that avoids leaving sensitive data lying around.

Good Idea, Unencrypted Reality

Docker Compose added a feature called secrets to keep passwords and API keys out of your Dockerfiles and environment variables. The idea sounds good. But here's the catch: those secrets are just plaintext files.

Compose bind-mounts a plaintext file into your container under /run/secrets ¹. No encryption.

As a result, in a running container, an attacker (or malicious process) can simply read the unencrypted file from /run/secrets and obtain your secret – these secret files are mounted world-readable (mode 0444) ¹.

Plaintext Secrets at Rest

Why is a plaintext file at rest such a big deal? Because anything stored on disk is one stray commit or backup away from exposure. If you check that secret file into source control by mistake, or if your server gets compromised, the secret is sitting there in plain text.

Docker Compose avoids putting secrets in images or environment variables, but leaving them on the filesystem means they persist longer than they might need to. Long-lived plaintext secrets are an inviting target.

For example, a common slip-up is a developer accidentally committing a .env or secret file to GitHub – now your passwords are public. Even on a server, a misconfigured web route could unintentionally serve that file, or an attacker could find it among backups.

A secret that lives as plaintext on disk is always at risk of being read by someone unauthorized.

Environment Variables

On the other hand, environment variables vanish once the process stops and aren't directly saved to disk. But environment variables have their own pitfalls if misused. If you print them in logs or leave them in an .env file on disk, you're back to square one.

The takeaway here is that how you handle the secret matters more than the mechanism. Simply moving a secret from an env var to a file doesn't automatically make it safe.

Dotenvx: Just-in-Time Secrets Injection

Dotenvx approaches secret management with a focus on minimal exposure. It injects your secrets at runtime only, via the command dotenvx run. How does this help?

First, it means you don't leave secret values sitting around in a container's environment or filesystem for longer than necessary. The dotenvx CLI loads the secrets from an encrypted .env file and injects them as environment variables only while launching your app, then your app uses them in-memory.

There's no separate plaintext secret file hanging around permanently. In CI/CD, for example, dotenvx will decrypt your secrets and inject them "just in time" as the build or app starts.

Dotenvx: Encryption

Crucially, dotenvx lets you encrypt your .env files. With one command dotenvx encrypt, you transform your .env into an encrypted format.

Even if someone finds that file, they can't read the secrets without the decryption key. It uses AES-256 encryption with ephemeral keys so that even if the encrypted .env file is exposed, its contents remain secure. ³ You can commit the encrypted .env to your repo safely – it's just gibberish to anyone without the key.

Come runtime, you provide the key (often via an environment variable or a secret manager) and dotenvx seamlessly decrypts and injects the real values into your app. The end result: no plaintext secrets sitting at rest on your disk or in your container. They exist only in memory when needed.

How It Works

You run your app like this:

$ dotenvx run -- node app.js

Secrets are decrypted and loaded as environment variables just for that process. Nothing written to disk. No lingering files in containers.

Want to commit secrets to your repo? Encrypt them first:

$ dotenvx encrypt

Then you can safely version your encrypted .env file. It's useless without the decryption key.

It's that easy and no plaintext files sitting around! Great!

Comparison

Takeaway

Docker Compose secrets look safer than env vars — but they aren't encrypted, and they persist longer. Meanwhile, dotenvx focuses on short-lived, encrypted, just-in-time secrets.

If you care about reducing blast radius and limiting exposure, dotenvx is a solid and modern option to consider.

To learn more, read the whitepaper.

¹ docker.com ² news.ycombinator.com ³ github.com/dotenvx/dotenvx

Dotenvx works with Claude MCP. Here's how to get it in your Claude.

Step 1

Type claude mcp add.

$ claude mcp add
Add MCP Server

Choose a unique name for this server:

> dotenvx

Step 2

For Server Scope, choose User.

Server Scope

Choose where this server will be available:

  
  Project (shared via .mcp.json)
  Local (private to you in this project)
> User (available in all your projects)

Step 3

For Transport Type, choose Stdio.

Transport Type

Choose how Claude Code will connect to your MCP server:

> Stdio (command-line process)
  SSE (Server-Sent Events over HTTP)

Step 4

Enter npx @dotenvx/dotenvx as the server command.

Server Command

Enter the full command to start your MCP server.

> npx @dotenvx/dotenvx

Confirm that. That's it!

Now you can ask Claude to encrypt my .env file and it will do it!

Hey Claude, encrypt my .env file please.

Bonus

Additionally, be sure to share llms.txt and llms-full.txt with Claude to make it smarter about all this.

Thanks for using Dotenvx.

If you enjoyed this post, please share dotenvx with friends or star it on GitHub to help spread the word.

That growth didn't happen by accident—dotenvx development has been heavy with 88 releases in 8 months. That's a new release every 2.75 days!

Today, it is a world-class tool–handling .env parsing, variable expansion, command substitution, encrypted .env files, and more better than anything else can. Each day, hundreds of software engineers newly learn of, and begin using, dotenvx.

As a result, it's starting to grow into something bigger—a community, an ecosystem, and a standard.

Community

Dotenvx has grown fast, and a big part of that is developer involvement. In just eight months, engineers have contributed ideas, issues, and pull requests that shaped its direction.

• GitHub Activity. More than 250 issues filed, 275 PRs created, and 60,000 lines of code written in the last eight months.
• Third-Party Documentation. Users wrote about dotenvx, made videos about dotenvx, recommended dotenvx, and much more.
• Adoption and Dependents. Most significantly, major projects adopted dotenvx and became dotenvx dependents.
  • NASA
  • AWS
  • Supabase
  • Cloudflare

This kind of community involvement makes dotenvx better. The feedback loop between users and development is tight, and that's been key to its fast growth.

Ecosystem

Dotenvx isn't just a CLI—it's extending into the tools developers use every day.

• VS Code Extension. Decrypt your encrypted .env files in VS Code with the Dotenvx VS Code Extension.
• Chrome Extension. Decrypt your encrypted .env files directly on GitHub with the Dotenvx Chrome Extension.
• Buildpacks. Install dotenvx to Heroku (or any platform that supports buildpacks) with the Dotenvx Buildpack.

This growing ecosystem ensures that no matter where developers work—local editors, browsers, or cloud platforms—dotenvx is increasingly there to seamlessly handle secrets.

Standard

Dotenvx isn't just widely used—it's built on a foundation that makes it the right way to handle secrets.

From the whitepaper:

Dotenvx: Reducing Secrets Risk with Cryptographic Separation

Abstract. An ideal secrets solution would not only centralize secrets but also contain the fallout of a breach. While secrets managers offer centralized storage and distribution, their design creates a large blast radius, risking exposure of thousands or even millions of secrets. We propose a solution that reduces the blast radius by splitting secrets management into two distinct components: an encrypted secrets file and a separate decryption key.

This approach—cryptographic separation—ensures that even if one component is compromised, the overall security of secrets remains intact. The whitepaper breaks down the problem and solution, and "it makes a great case for dotenvx." ¹

By stating the problem well and implementing good DX, dotenvx is emerging as a new standard for secrets management of .env files. It's pretty incredible.

Conclusion

What started as a rethink of .env files has quickly turned into something much bigger. In just eight months, dotenvx has gone from an emerging idea to an essential tool, trusted by developers and major platforms alike.

With over 1 million monthly installs, an active and engaged community, an expanding ecosystem, and a well-defined standard, dotenvx isn't just growing—it's reshaping how secrets are managed in modern development.

And this is only the beginning. 💪

If you enjoyed this post, please share dotenvx with friends or star it on GitHub to help spread the word.