How to manage environment variables in Netlify

Introduction

Environment variables are one of the most important building blocks of modern web applications. They allow you to configure behavior without hardcoding secrets or environment-specific values into your code.

Netlify provides a powerful and flexible system for managing environment variables across build time, runtime, and different deploy contexts. In this guide, you’ll learn how Netlify environment variables work and how to use them safely and effectively.

What are environment variables

Environment variables are key-value pairs that are injected into your application at build time or runtime.

They are commonly used for:

API keys and tokens
Feature flags
Environment-specific configuration
Build-time behavior toggles

Keeping these values out of your repository helps avoid accidental leaks and makes deployments easier to manage.

Where Netlify environment variables apply

Netlify environment variables can be used in three main places:

During builds
In serverless functions
In edge functions

They are not directly available in static HTML unless injected during the build.

Adding environment variables in the Netlify dashboard

The most common way to add environment variables is through the Netlify dashboard.

Open your site in the Netlify dashboard
Go to Site configuration → Environment variables
Click Add a variable
Enter a key and value
Save

Once added, the variable will be available on the next deploy.

Using environment variables in builds

Environment variables are automatically available to your build process.

For example, in a JavaScript build:

console.log(process.env.MY_VARIABLE)

This is commonly used in static site generators like Next.js, Astro, Gatsby, and Hugo.

Exposing variables to client-side code

By default, environment variables are not exposed to browser code.

Most frameworks require a prefix to make variables public:

Next.js: NEXT_PUBLIC_
Astro: PUBLIC_
Vite: VITE_

Example:

NEXT_PUBLIC_API_URL=https://api.example.com

Only use public variables for values that are safe to expose.

Environment variables in serverless functions

Netlify Functions automatically receive environment variables.

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

This is the recommended place for sensitive credentials like API keys.

Deploy context-specific variables

Netlify supports different values for different deploy contexts:

Production
Deploy previews
Branch deploys

This allows you to use different APIs or credentials per environment.

Example use cases:

Production API vs staging API
Feature flags for previews
Debug logging in non-production builds

Environment variables via netlify.toml

You can define environment variables in netlify.toml, but this is best suited for non-sensitive values.

[build.environment]
  NODE_VERSION = "20"

Never store secrets in version-controlled files.

Using environment variables locally

When running Netlify locally, you can use a .env file.

API_SECRET=local-secret

The Netlify CLI automatically loads these variables during local development.

Common mistakes to avoid

Some common pitfalls include:

Forgetting to redeploy after changing variables
Exposing secrets to client-side code
Hardcoding fallback values
Mixing production and preview credentials

Always treat environment variables as part of your deployment configuration, not your code.

Best practices

Follow these guidelines for safer setups:

Store secrets only in the dashboard
Use context-specific values
Prefix public variables explicitly
Keep variable names consistent
Rotate credentials regularly

Conclusion

Environment variables are essential for secure and flexible Netlify deployments. Once you understand where and how they apply, you can confidently manage secrets, configuration, and environment-specific behavior without risking your codebase.

Used correctly, Netlify’s environment variable system scales cleanly from hobby projects to production applications.