Use dotenvx with Netlify

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

[[plugins]]
  package = "@netlify/plugin-nextjs"

[build]
  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

yourapp.netlify.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.

Run 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"
},

Add production environment

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

# .env.production
HELLO="production"

Encrypt production

npm run dotenvx -- set HELLO production --encrypt -f .env.production

Your .env.production file is now encrypted, and you have a .env.keys file.

#/-------------------[DOTENV_PUBLIC_KEY]--------------------/
#/            public-key encryption for .env files          /
#/       [how it works](https://dotenvx.com/encryption)     /
#/----------------------------------------------------------/
DOTENV_PUBLIC_KEY_PRODUCTION="025a54defaeff32caa2bbe60537b88b5b89716eade6df08418d7a68f5c4f742be6"

# .env.production
HELLO="encrypted:BD+uttK9iBuXnfx6HukDK06IGk0pQARwivtxM+ZiePvhRxHyQL3UD0sf0ayLw/P5Y/BED//zRiTlUf6nENuu7QhNJ24g3uADfrDfhvYi/MOHjmfKyRiu+yOxSw6e+c0yRNukS+n8SxONnec="

#/------------------!DOTENV_PRIVATE_KEYS!-------------------/
#/ private decryption keys. DO NOT commit to source control /
#/     [how it works](https://dotenvx.com/encryption)       /
#/----------------------------------------------------------/

# .env.production
DOTENV_PRIVATE_KEY_PRODUCTION="424d0ea072eb17c6bee9b4b42ff6333513cf128ea3d5d60ccf79246ca7c3f786"

You SHOULD commit .env.production to code. It is now encrypted, safe, and recommended to do so. But DO NOT commit .env.keys to code. Keep them somewhere safe like 1Password.

We're ready to inject the encrypted .env.production secrets into the app on boot.

Set decryption key

Set DOTENV_PRIVATE_KEY_PRODUCTION on Netlify using the production key in your .env.keys file.

npx netlify-cli@latest env:set DOTENV_PRIVATE_KEY_PRODUCTION "424d0ea072eb17c6bee9b4b42ff6333513cf128ea3d5d60ccf79246ca7c3f786"

Redeploy.

npx netlify-cli@latest deploy --build --prod

Your app restarts and env is successfully injected using the encrypted contents of .env.production.

$ npm run build

> build
> dotenvx run -- next build

[[email protected]] injecting env (2) from .env.production
✓ Compiled successfully

Visit your url and it says Hello production.

yourapp.netlify.app

You succesfully add encryption to your .env files. This is safer than scattering your secrets across third-party platforms and tools. When you need to update a secret, run dotenvx set KEY value --encrypt 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.

npm run dotenvx -- set HELLO Mot --encrypt

Commit .env.production safely to code and redeploy.