Cloudflare

Use Dotenvx with Cloudflare.

Prerequisites

Create a Cloudflare Worker. Choose the Hello World example and JavaScript to follow along.

Install

In your Worker project, install Dotenvx and Wrangler.

$ npm install --save-dev @dotenvx/dotenvx
$ npm install --save-dev wrangler@latest

$ pnpm add -D @dotenvx/dotenvx
$ pnpm add -D wrangler@latest

Encrypt

Start with a secret value in the .env file at your project root, like:

# .env
HELLO="Secret"

Encrypt it with a single command.

$ npx dotenvx encrypt
◈ encrypted .env (022 0D8) via .env.keys ⛉

$ pnpm exec dotenvx encrypt
◈ encrypted .env (022 0D8) via .env.keys ⛉

The values become ciphertext and only your private key can unlock them.

# .env
DOTENV_PUBLIC_KEY="0220d830351410598be484f43a7b07097e09851f50426832876e8b5815a1752990"

HELLO="encrypted:BHLTACNJMr00nTG6yXpkCyWFKF/MY0ajN855tg3uVtKopTe2AGzSkQlcPd21pTOT3Ci8IKrdIg2TMZFoq1mDR6yb06QCRvqHXtpkZkAHYCEHfeWqqC8tMFovcYq5JS2uZSrC/qUGDA=="

Commit

Commit your encrypted .env files with your code. It's safe. Now you can securely share secrets through git. Keep .env.keys out of git. The -f flag adds the encrypted file even if your project ignores .env files.

$ git add -f .env
$ git commit -m "encrypt .env"

Ship

Read your secrets through env. Update src/index.js:

// src/index.js
export default {
  async fetch(request, env) {
    return new Response(`Hello ${env.HELLO}`)
  }
}

Add HELLO to the required secrets in your existing Wrangler configuration:

{
  "secrets": {
    "required": ["HELLO"]
  }
}

Wrangler loads these named secrets from the process environment during local development. Use .env for this setup and do not create a .dev.vars file; Wrangler gives .dev.vars precedence over the .env and process-environment loader.

Update the dev script in your existing package.json:

{
  "scripts": {
    "dev": "dotenvx run -- wrangler dev"
  }
}

Run your Worker:

$ npm run dev

$ pnpm dev

Dotenvx decrypts .env into the process environment. Wrangler gives those values precedence over the encrypted file and makes HELLO available to your Worker as env.HELLO. See Wrangler's local environment handling.

Visit http://localhost:8787 to see Hello Secret.

Hello Secret

Have teammates? Share access with Dotenvx Armor ⛨

$ npx dotenvx login
◉ logged in (username)

$ pnpm exec dotenvx login
◉ logged in (username)

Create the Armored Key ⛨

$ npx dotenvx armor up
⛨ armored .env (022 0D8)

$ pnpm exec dotenvx armor up
⛨ armored .env (022 0D8)

Invite your teammate.

$ npx dotenvx armor invite
⛨ invited [email protected] to team

$ pnpm exec dotenvx armor invite
⛨ invited [email protected] to team

Your teammate accepts the invitation, pulls the repository, installs dependencies, and logs in with dotenvx login. With the Wrangler configuration and dev script from Ship, they can then run the Worker:

$ npm run dev

$ pnpm dev

Dotenvx decrypts .env through Armor and passes the values to Wrangler.

Visit http://localhost:8787 to see Hello Secret.

Hello Secret

Not using Armor? Alternative →

Production

Create a .env.production file.

# .env.production
HELLO="Production"

Encrypt it:

$ npx dotenvx encrypt -f .env.production

$ pnpm exec dotenvx encrypt -f .env.production

Store the production key in Armor so authorized teammates can deploy:

$ npx dotenvx armor up -f .env.production

$ pnpm exec dotenvx armor up -f .env.production

Commit .env.production. Keep .env.keys out of git.

$ git add -f .env.production
$ git commit -m "encrypt .env.production"

$ npx wrangler login

$ pnpm exec wrangler login

Add the deploy script to your existing package.json, keeping the dev script from Ship:

{
  "scripts": {
    "dev": "dotenvx run -- wrangler dev",
    "deploy": "bash -c 'dotenvx_secrets=\"$(dotenvx get -f .env.production --strict)\" && wrangler deploy --secrets-file <(printf \"%s\" \"$dotenvx_secrets\")'"
  }
}

The deploy script requires Bash. Deploy your Worker:

$ npm run deploy

$ pnpm deploy

Dotenvx decrypts .env.production through Armor. The && runs Wrangler only if decryption succeeds, and process substitution passes the JSON without saving a plaintext secrets file.

Wrangler uploads the secrets alongside your code. Cloudflare stores the values as Worker secrets, and your Worker reads env.HELLO. The Dotenvx private key stays with Armor; the Worker does not need it.

Open the workers.dev URL printed by Wrangler to see Hello Production.

Hello Production

Using Cloudflare Pages? Alternative →

Want to decrypt inside your Worker? Advanced →

Conclusion

You've encrypted your secrets, shared access with Armor, and deployed your Worker with Wrangler. Your encrypted .env files travel with your code, and Cloudflare serves your production secrets through env.