Vercel Environment Variables

Your app is gonna need secrets at some point. Passwords, API keys, that kind of thing. And you do NOT want those sitting in your code where anybody can read them. That's the whole job of environment variables.

What Are Environment Variables?#

Think of environment variables as hidden settings for your app. They hold information that fits one of these.

• Changes between different environments (development vs production)
• Should be kept secret (API keys, passwords)
• You don't want in your code

If you went through the Railway chapter, this will feel familiar. Vercel uses the same idea with a few extra features bolted on.

Why Environment Variables Matter#

Say your app uses a service that needs an API key. You could paste the key right into your code.

// Don't do this!
const apiKey = "sk_live_12345secret67890";

Here's why that's a bad idea.

1. Anyone who sees your code sees your secret
2. GitHub stores your code, so your secret is saved forever
3. If you push to a public repository, the whole world can see it

So you use an environment variable instead.

// Do this instead
const apiKey = process.env.API_KEY;

The real value lives safely in Vercel, and your code just points at it.

Vercel's Three Environments#

Vercel knows your app runs in a few different places.

Production#

This is your live site, the one real users visit. Production environment variables kick in when somebody goes to your main URL.

Preview#

These are your preview deployments. Every pull request creates one, and preview environment variables get used for those temporary deployments.

Development#

This is your own computer while you're building and testing. Development environment variables help your app run locally.

Adding Environment Variables#

Here's how to add one to your Vercel project.

Step 1. Go to Your Project#

Log in to Vercel and click on the project you want to set up.

Step 2. Open Settings#

Click the "Settings" tab at the top of the project page.

Step 3. Find Environment Variables#

In the left sidebar, click "Environment Variables."

Step 4. Add a Variable#

You'll see a form with three fields.

• Name - The variable name (like API_KEY)
• Value - The actual secret value
• Environment - Which environments should have this variable

Step 5. Choose Environments#

Check the boxes for where this variable should show up.

• Production
• Preview
• Development

For most variables you'll just check all three.

Step 6. Save#

Click "Save" and the variable is added. Your NEXT deployment can use it (more on that in a sec).

Common Environment Variable Patterns#

Here are a few you'll probably run into.

API Keys#

Name: STRIPE_SECRET_KEY
Value: sk_live_abc123...
Environments: Production only
 
Name: STRIPE_SECRET_KEY
Value: sk_test_xyz789...
Environments: Preview, Development

See what's happening there? It's the SAME name added twice with different values. Your code always reads process.env.STRIPE_SECRET_KEY, but the real key only goes to production and previews get a test key. That way you never accidentally charge a real customer while you're testing (that's a phone call nobody wants to make).

Database Connections#

Name: DATABASE_URL
Value: postgresql://user:pass@host/db
Environments: Production, Preview, Development

You might use the same database everywhere, or a different one for each environment.

Feature Flags#

Name: ENABLE_NEW_FEATURE
Value: true
Environments: Preview only

That lets you test new features in previews before you turn them on in production.

Sensitive vs Regular Variables#

Some variables are touchier than others, so Vercel lets you mark them as "Sensitive."

Regular Variables#

• Visible to project members in the dashboard
• Can be viewed and copied

Sensitive Variables#

• Hidden in the dashboard (shown as dots)
• Can only be replaced, not viewed
• Good for passwords and API keys

To mark a variable as sensitive, flip the "Sensitive" toggle when you create it. That toggle only works for Production and Preview, not Development.

Using Variables in Your Code#

Once your variables are in Vercel, your app reads them with process.env.

// Access an environment variable
const databaseUrl = process.env.DATABASE_URL;
 
// Use it in your app
console.log("Connecting to database...");

In Next.js, variables that start with NEXT_PUBLIC_ get exposed to the browser.

// Available in browser code
const publicUrl = process.env.NEXT_PUBLIC_SITE_URL;

Syncing with Local Development#

Vercel can help keep your local setup in sync too. You've got two options.

Download Variables#

Use the Vercel CLI to pull your environment variables down to your machine. Install it once, then link your project folder to your Vercel project (it walks you through logging in the first time).

npm i -g vercel

vercel link

vercel env pull .env.local

That creates a .env.local file with your development variables in it.

Use Different Local Values#

Or just make your own .env.local file with local settings. Just don't commit it to Git!

Add these lines to your .gitignore.

.env.local
.env

Editing and Deleting Variables#

To change a variable, here's the drill.

1. Go to Settings > Environment Variables
2. Find the variable you want to change
3. Click the three dots menu
4. Select "Edit" to change the value
5. Or select "Remove" to delete it

Environment Variable Best Practices#

DO:#

• Use descriptive names like DATABASE_URL instead of DB
• Keep secrets out of your code
• Use different values for production and test
• Mark sensitive values as sensitive

DON'T:#

• Put API keys directly in your code
• Commit .env files to GitHub
• Use production secrets in development
• Share sensitive values in chat or email

TL;DR#

• Environment variables keep secrets and settings out of your code
• Vercel has three environments, called Production, Preview and Development
• You can give each environment its own value
• Sensitive variables stay hidden in the dashboard
• Redeploy after you change a variable or the change won't show up

What's Next?#

You can deploy, preview and configure your app now. Next up is serverless functions, which let you add backend logic right inside your frontend project...