Use dotenvx with Netlify

Use dotenvx with Netlify

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 netlify.toml file.

  package = "@netlify/plugin-nextjs"

  command = "npm run build"
  publish = ".next"

Commit to code and deploy to Netlify.

brew install vips # most machines can skip this step
npx netlify-cli@latest deploy --build --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 Netlify.

npx netlify-cli@latest deploy --build --prod
$ npm run build

> build
> dotenvx run -- next build

[[email protected]] missing .env file (/../jan-24/netlify-next/.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 Netlify cli, but you can also use their dashboard.

npx netlify-cli@latest env:set DOTENV_KEY "dotenv://"


npx netlify-cli@latest deploy --build --prod
$ npm run build

> build
> dotenvx run -- next build

[[email protected]] injecting env (1) from encrypted .env.vault
✓ 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 netlify-cli@latest deploy --build --prod