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.keys

Add .gitignore file.

.gitignore

# gitignore
!.env.production
.env.keys

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.

Run dotenvx

Install dotenvx.

npm install @dotenvx/dotenvx --save

For Next.js, swap process.env for dotenvx.get. For Astro, you can leave things using import.meta.env.

// app/page.tsx
import * as dotenvx from '@dotenvx/dotenvx';
export default function Page() {
  return <h1>Hello {dotenvx.get('HELLO')}</h1>;
}

If using Next.js Page Router, change your code to something like this:

import * as dotenvx from '@dotenvx/dotenvx';

export default function Page({ hello }: { hello: string }) {
  return <h1>Hello {hello}</h1>;
}

export function getServerSideProps() {
  const hello = dotenvx.get('HELLO')
  return {
    props: {
      hello,
    },
  };
}

Add dotenvx to your scripts.

...
"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 -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 or dotenvx pro.

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

Set decryption key

Set DOTENV_PRIVATE_KEY_PRODUCTION on Vercel using the production key in your .env.keys file. We'll use the Vercel cli, but you can also use their dashboard.

npx vercel@latest env add DOTENV_PRIVATE_KEY_PRODUCTION

? What’s the value of DOTENV_PRIVATE_KEY_PRODUCTION? 424d0ea072eb17c6bee9b4b42ff6333513cf128ea3d5d60ccf79246ca7c3f786
✅  Added Environment Variable DOTENV_PRIVATE_KEY_PRODUCTION to Project nodejs-vercel [94ms]

Or set it in the Vercel UI.

vercel.com

Redeploy.

npx vercel@latest deploy --prod

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

$ npx vercel@latest logs https://yourapp.vercel.app
Running "npm run build"

> build
> dotenvx run -- next build

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

Visit your url and it says Hello production.

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

Commit .env.production safely to code and redeploy.