Use dotenvx with Vercel

Use dotenvx with Vercel

Initial setup

Install the necessary web server libraries in the framework of your choice.

npx create-next-app@latest --example hello-world .

Create a simple Hello World program.

// app/page.tsx
export default function Page() {
  return <h1>Hello {process.env.HELLO}</h1>;

Add .vercelignore file.


# vercelignore

Commit to code and deploy to Vercel.

npx vercel@latest deploy --prod

Once deployed, your app will say 'Hello [blank]' as it doesn't have a way to access the environment variable yet. Let's do that next.

Install dotenvx

Install dotenvx.

npm install @dotenvx/dotenvx --save

Preload scripts with dotenvx. This will inject environment variables ahead of any build, start, or dev commands.

"scripts": {
  "dotenvx": "dotenvx",
  "dev": "dotenvx run -- next dev --turbo",
  "build": "dotenvx run -- next build",
  "start": "dotenvx run -- next start"

Encrypt secrets

Create .env.production in the root of your project.

# .env.production

Encrypt it to .env.vault.

npm run dotenvx encrypt

The .env.vault file contains encrypted (AES-256-GCM) versions of your secrets, and the .env.keys file contains the decryption keys.


#/         cloud-agnostic vaulting standard         /
# production


#/   DOTENV_KEYs. DO NOT commit to source control   /

Redeploy to Vercel.

npx vercel@latest deploy --prod
$ npx vercel@latest logs
Running "npm run build"

> build
> dotenvx run -- next build

[[email protected]] missing .env file (/vercel/path0/.env)
? in development: add one with [echo "HELLO=World" > .env] and re-run [dotenvx run -- next build]
? for production: set [DOTENV_KEY] on your server and re-deploy

The logs tell us missing .env file. This is expected, as we don't want to commit .env to code. It also tells us, for production, that we should set DOTENV_KEY. That is what we want to do. Let's do that next.


Set DOTENV_KEY to the DOTENV_KEY_PRODUCTION value. We'll use the Vercel cli, but you can also use their dashboard.

npx vercel@latest env add DOTENV_KEY
? What’s the value of DOTENV_KEY? dotenv://:[email protected]/vault/.env.vault?environment=production
✅  Added Environment Variable DOTENV_KEY to Project nodejs-vercel [94ms]


npx vercel@latest deploy --prod
$ npx vercel@latest logs
Running "npm run build"

> build
> dotenvx run -- next build

[[email protected]] injecting env (1) from encrypted .env.vault
   Creating an optimized production build ...
 ✓ Compiled successfully

Your app restarts and env is successfully injected using the encrypted contents of .env.vault. Visit your url and it says Hello production.

Great job! That's pretty much it. See the bonus section(s) below to go a little deeper.


Try changing the value of .env.production to your name.


# .env.production

Re-encrypt it.

dotenvx encrypt

Commit .env.vault safely to code and redeploy.

git commit -am "update production secret"
npx vercel@latest deploy --prod