Use dotenvx with Netlify
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
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 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
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://:key_10283719af6a30ef49050048617f4fea10c23a38021fbebeb9fd858caa01852e@dotenvx.com/vault/.env.vault?environment=production"
Redeploy.
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
.
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 netlify-cli@latest deploy --build --prod