Use dotenvx with Vercel

Find code examples for this guide on GitHub.

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

# vercelignore
.env*
!.env.vault

Commit to code and deploy to Vercel.

npx vercel@latest deploy --prod

yourapp.vercel.app

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
HELLO="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.

.env.vault

#/-------------------.env.vault---------------------/
#/         cloud-agnostic vaulting standard         /
#/--------------------------------------------------/
# production
DOTENV_VAULT_PRODUCTION="YZkhtbh1IlzBgIamAAsG5nzGPfH6p8Zbuj9egXoziviVu/eYIyNjJWtIYyhiW/vHhFbqbsvo5+P9b27OC6ZC7qU="

.env.keys

#/!!!!!!!!!!!!!!!!!!!.env.keys!!!!!!!!!!!!!!!!!!!!!!/
#/   DOTENV_KEYs. DO NOT commit to source control   /
#/--------------------------------------------------/
DOTENV_KEY_PRODUCTION="dotenv://:key_10283719af6a30ef49050048617f4fea10c23a38021fbebeb9fd858caa01852e@dotenvx.com/vault/.env.vault?environment=production"

You SHOULD commit .env.vault to code. It is safe and recommended to do so. But DO NOT commit .env.keys to code. Keep them somewhere safe like 1Password or dotenvx hub.

Redeploy to Vercel.

npx vercel@latest deploy --prod

$ npx vercel@latest logs https://yourapp.vercel.app
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

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]

Redeploy.

npx vercel@latest deploy --prod

$ npx vercel@latest logs https://yourapp.vercel.app
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.

yourapp.vercel.app

You succesfully used the new .env.vault standard to encrypt and deploy your secrets. This is much safer than scattering your secrets across multiple third-party platforms and tools. Whenever you need to add or change a secret, just re-encrypt .env.vault and redeploy.

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

Bonus

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

.env.production

# .env.production
HELLO="Mot"

Re-encrypt it.

dotenvx encrypt

Commit .env.vault safely to code and redeploy.

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

Platforms › Vercel