How-To Guide

How to Set Up Netlify Environment Variables

Securely configure secrets for your Netlify deployments

TL;DR

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

Open your Netlify site

Go to app.netlify.com and select your site from the dashboard.

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

Most variables should have both Builds and Functions enabled.

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. Make sure to add .env to your .gitignore.