How to Set Up Netlify Environment Variables
The most common Netlify env var mistake is adding a variable and wondering why it's not available in your function. It's because you didn't enable the Functions scope. Netlify splits env var access into three scopes (Builds, Functions, Post processing) and you have to opt each variable into the right one.
TL;DR
Go to Site Configuration → Environment Variables in your Netlify dashboard. Add key-value pairs and set the scope (Builds, Functions, or both). Use deploy contexts to set different values for production vs branch deploys. Trigger a deploy with cleared cache to apply changes.
Step-by-Step Setup
Navigate to Environment Variables
Click on Site configuration in the left sidebar, then select Environment variables.
Add a new variable
Click Add a variable and enter:
- Key: Variable name (e.g.,
STRIPE_SECRET_KEY) - Values: The secret value(s) for each context
Configure scopes
Choose where the variable should be available:
| Scope | Available In | Use For |
|---|---|---|
| Builds | Build process, SSG | Build-time secrets |
| Functions | Netlify Functions, Edge | Runtime API keys |
| Post processing | Netlify plugins | Plugin configuration |
Default to enabling both Builds and Functions for most variables. If it's only used at build time (SSG, Next.js data fetching), Builds alone is fine.
Set deploy contexts (optional)
You can set different values for different environments:
- All deploy contexts: Same value everywhere
- Production: Only for production deploys
- Deploy Previews: For PR preview builds
- Branch deploys: For specific branch deployments
Trigger a new deploy
Go to Deploys → Trigger deploy → Clear cache and deploy site. This ensures your new variables take effect.
Using netlify.toml for Environment Variables
You can reference environment variables in your netlify.toml file, but never store actual secrets there:
# netlify.toml
[build]
command = "npm run build"
publish = "dist"
[context.production]
environment = { NODE_ENV = "production" }
[context.deploy-preview]
environment = { NODE_ENV = "staging" }
# Don't put secrets in netlify.toml - use the dashboard!
Accessing Variables in Your Code
In Netlify Functions
// netlify/functions/api.js
export const handler = async (event) => {
const apiKey = process.env.STRIPE_SECRET_KEY;
if (!apiKey) {
return { statusCode: 500, body: 'Missing API key' };
}
// Use the key...
};
In Build Process (SSG)
// Available at build time
const supabaseUrl = process.env.SUPABASE_URL;
// For frameworks like Astro, Vite
const apiUrl = import.meta.env.VITE_API_URL;
Build-time vs Runtime
Variables used in static site generation are embedded at build time. To use secrets at runtime (when users visit your site), you need Netlify Functions or Edge Functions.
Using the Netlify CLI
# List all environment variables
netlify env:list
# Set a variable
netlify env:set STRIPE_SECRET_KEY "sk_test_xxxxx"
# Set for specific context
netlify env:set STRIPE_SECRET_KEY "sk_live_xxxxx" --context production
# Get a variable value
netlify env:get STRIPE_SECRET_KEY
# Delete a variable
netlify env:unset STRIPE_SECRET_KEY
# Pull variables to .env for local dev
netlify env:pull
Framework-Specific Notes
Next.js on Netlify
# Server-side only
DATABASE_URL=postgresql://...
# Exposed to browser (be careful!)
NEXT_PUBLIC_API_URL=https://api.example.com
Astro on Netlify
# Server-side (in .ts files, API routes)
SECRET_KEY=xxxxx
# Client-side (use PUBLIC_ prefix)
PUBLIC_API_URL=https://api.example.com
Why aren't my environment variables working?
Make sure you've enabled the right scopes (Builds and/or Functions). Then clear cache and redeploy. If using a framework, check if it requires a specific prefix (like NEXT_PUBLIC_ or VITE_).
Can I use environment variables in redirects?
No, environment variables cannot be used in the _redirects file or the redirects section of netlify.toml. These are processed at the edge and don't have access to your build-time variables.
How do I sync environment variables for local development?
Use netlify env:pull to download your variables to a local .env file. Add .env to your .gitignore before you do this; the pull command creates the file immediately.
Related guides:Environment Variables Guide · Vercel Environment Variables · How to Hide API Keys