Netlify Environment Variables: How to Set, Scope, and Debug Them

Environment variables are one of those things that work perfectly until they don't — and when they don't, the error messages are terrible. "undefined is not a function" because your API key didn't make it to the build. Fun.

Netlify's env var system is actually pretty flexible once you understand how it's structured. You can scope variables per deploy context, keep secrets out of your repo, and use different values for production vs. preview. Here's how it all works.

What they're for

Environment variables are key-value pairs injected into your app at build time or runtime. You've probably used them for:

• API keys and tokens
• Feature flags
• Database URLs
• Environment-specific config (staging vs. production API endpoints)

The important part: they stay out of your Git repo, which means no accidentally committing your Stripe secret key to a public repo.

Where they work on Netlify

Netlify env vars are available in three places:

• During builds — your build process can read them via process.env
• In serverless functions — Netlify Functions get them automatically
• In edge functions — same deal

They're not available in static HTML unless your build step injects them. This trips people up constantly.

Adding variables in the dashboard

The most common way:

1. Open your site in the Netlify dashboard
2. Go to Site configuration > Environment variables
3. Click Add a variable
4. Enter a key and value
5. Save

The variable becomes available on the next deploy. If you just added it and your site seems to ignore it, you probably need to redeploy. This catches people more often than you'd think.

Making variables available in the browser

By default, environment variables are server-side only. They don't get bundled into your JavaScript. To expose one to client-side code, your framework needs a specific prefix:

• Next.js: NEXT_PUBLIC_
• Astro: PUBLIC_
• Vite: VITE_
• Gatsby: GATSBY_

So if you want your API URL available in the browser:

NEXT_PUBLIC_API_URL=https://api.example.com

Only do this for values that are genuinely safe to expose. API keys, tokens, database URLs — those should stay server-side.

Using them in serverless functions

Netlify Functions receive env vars automatically:

export const handler = async () => {
  const secret = process.env.API_SECRET
  // use it...
  return { statusCode: 200 }
}

This is the right place for sensitive credentials. The function runs server-side, so nothing leaks to the browser.

Different values per deploy context

This is one of my favorite Netlify features. You can set different values for:

• Production — your live site
• Deploy previews — PR preview builds
• Branch deploys — specific branch deployments

So your production site hits the real API, but deploy previews hit the staging API. No more accidentally sending test data to production because you forgot to change an env var.

Set this up in the dashboard when adding a variable — there's a dropdown to choose which context it applies to.

Variables in netlify.toml

You can also define env vars in netlify.toml, but only for non-sensitive values:

[build.environment]
  NODE_VERSION = "20"

Never put secrets here. This file is in your repo, and anyone with access can read it.

Local development

When running locally with the Netlify CLI, create a .env file:

API_SECRET=local-secret

The CLI loads these automatically during netlify dev. Just make sure .env is in your .gitignore.

The mistakes I see constantly

Forgetting to redeploy after adding a variable. The variable doesn't take effect until the next build. If you add it and refresh the site, nothing changes.

Exposing secrets to the client. If you prefix something with NEXT_PUBLIC_ or VITE_, it ends up in your JavaScript bundle. Anyone can see it in the browser's dev tools.

Using the wrong context. Your production API key shouldn't be in deploy previews. Scope your variables properly.

Hardcoding fallbacks. Writing process.env.API_URL || "https://api.example.com" defeats the whole purpose. If the variable is missing, you want to know about it — not silently fall back to something that might be wrong.

Practical guidelines

• Store secrets in the dashboard, never in netlify.toml or source code
• Use deploy context scoping for anything that differs between environments
• Prefix client-side variables explicitly — and think twice before exposing anything
• Keep variable names consistent across environments
• Rotate credentials periodically, especially after team changes

Environment variables aren't glamorous, but getting them right saves you from some truly annoying debugging sessions.