[Common Issue] Using environment variables on Netlify correctly

The preferred way to use environment variables in Netlify is to set them in our environment - be that in the Build Environment Variables configuration widget (on the site’s “Build & Deploy settings” page), or via netlify.toml. The latter is a bit more flexible as you can set different values for different contexts - e.g. staging uses a staging $API_ENDPOINT and production uses a production one; the former is a bit more secure, since only people with access to the Netlify admin UI for your site can see them, rather than “anyone who can clone your repo!”

These variables are made available mostly in the build environment - if your build command were env, then you’d see them listed - in addition to $PATH and $NODE_VERSION and some other stuff Netlify sets automatically. However, depending on how your build pipeline works, the variables may or not be available once your build command starts. If your build command is node -p "process.env" - that will show you what Node.js sees for environment variables - and that should show the same thing as env shows (which is what the shell run by the build script sees). This generally works correctly automatically and you don’t have to do those experiments to prove that the variables were or weren’t set unless you are debugging new settings in netlify.toml.

However, some of the build pipelines that folks use DON'T automatically import/inherit variables from the parent shells. This thread shows such an example. So - the best practice is not to necessarily use something like dotenv but instead, use a build process that appropriately passes those environment variables that we expose in the shell, into the build environment. How you do that is up to you and your tools.

So now you have the variables set and available to your build process, great! But, unless your build pipeline DOES something with the environment variable - it's not going to be much use in the code that gets published and served to the browser - which doesn't understand $API_ENDPOINT - that's just a string to the browser and to our CDN. Only the build environment knows about and can use environment variables in most cases, since they are set in the shell during build, but your code is not served from the build environment - it is served without modification after build.

There are some specific other use cases that enable environment variables at browse time, such as:

You can also check a full list of environment variables recognized by Netlify here.


But how do we acutally used those evnironment variables inside the site.

1 Like

Hi @mittalyashu.

It seems like you’re asking about how to leverage environment variables throughout your source code, since I assume you read the above post, and understand that:

Only the build environment knows about and can use environment variables in most cases, since they are set in the shell during build, but your code is not served from the build environment - it is served without modification after build.

dotenv (linked above) is a popular npm module that allows you to leverage environment variables in a project. It allows you to set secret variables and reference them in public code elsewhere, like connecting to a database for example:

# .env file in project root

// server.js file

const db = require('db')

  host: process.env.DB_HOST,
  username: process.env.DB_USER,
  password: process.env.DB_PASS

Yes, I am aware of that dotenv package.

But in order to use that package we have to define the .env file in the repository to use the defined variables, which means if the repository source code is public, then anyone can have access to the environment variables.

I answered using .env on Netlify to be able to use dotenv on your build on SO, but here is the cross post:

WARNING: If this is a secret key, you will not want to expose this environment variable value in any bundle that gets returned to the client. It should only be used by your build scripts to be used to create your content during build.


dotenv-webpack expects there to be a .env file to load in your variables during the webpack build of your bundle. When the repository is checked out by Netlify, the .env does not exist because for good reason it is in .gitignore.


Store your API_KEY in the Netlify build environment variables and build the .env using a script prior to running the build command.


const fs = require('fs')
fs.writeFileSync('./.env', `API_KEY=${process.env.API_KEY}\n`)

Run the script as part of your build

node ./scripts/create-env.js && <your_existing_webpack_build_command>

Caveats & Recommendations

  • Do not use this method with a public facing repository if you are trying to hide the keys [open] because any PR or branch deploy could create a simple script into your code to expose the API_KEY
  • Only use the private keys for your build env. Public environment variables are safe to access inside your client code bundles.
  • The example script above is for simplicity so, make any script you use be able to error out with a code other than 0 so if the script fails the deploy will fail.

@brianzelip, I can’t seem to determine why I keep getting the following error: Invalid environment value for ‘GIT_LFS_ENABLED’. What should I have this variable equal to? Are there requirements for this variable?

hi @stephlane544 - i don’t have a specific answer for you right now, but this answer is related to Git large file service - you may ask in the #netlify-platform:large-media category which is related (if not quite the same).

1 Like

Hi @stephlane544, we answered you in GIT_LFS_ENABLED error!

Hello mittalyashu. Your repo may be public but the way to get around having it exposed to your remote repository (if you’re using git) is to include the .env file in your .gitignore file. Assuming that your .env file is in your head director you would simply type the filepath relative to your head repository to where the .env file is. For me this looked like:

(assume we’re in .gitignore)


1 Like

wrote up an introductory post on env vars in case this helps anyone https://scotch.io/@sw-yx/netlify-environment-variables-the-cheat-codes-of-the-internet

@christiancw, does that edit mean that you solved the issue?

Edit: needed to add dotenv to my webpack plugins.

Not quite. I had thought so, since it worked when I ran netlify dev but then the keys still are not being passed to my React component when I deploy the site - though I can tell they are accessible at build time. With the keys stored on the Netlify UI, and with a create-env script, is there any other reasons the keys wouldn’t be available on process.env in the React component?

Sharing what worked for me, for a Netlify lambda function:

  1. Adding environment variables through Netlify’s UI widget (on the site’s “Build & Deploy settings” page).

  2. netlify.toml

    Command = "npm run lambda-build"
    Functions = "lambda"
  1. Adding node -p 'process.env' to my package.json lamba-build command:

"lambda-build": "netlify-lambda build functions && node -p 'process.env'"

This way, when the function is deployed, env variables will we loaded and available to the function.

thanks for sharing this, @ramigs!

Hey!! I tried this and the script runs fine, it seems. But, I can still only access env vars defined manually in my dashboard. I’m trying to access the COMMIT_REF, NODE_ENV, etc. for inside my zip-it-and-ship-it functions.

I have this:


But, everything is still undefined, except when I tested NODE_ENV by adding NODE_ENV=development to the dashboard env vars.

Any thoughts?

Only environment variables in the dashboard are available at the time of a function execution in Netlify Functions at the time of this answer. :yum:

Ah, ok. So there’s no possibly way to expose COMMIT_REF or even NODE_ENV in functions? Seems like some crucial environment functionality, right? Maybe I’m missing something.

For now, I’m checking to see if NETLIFY_DEV exists, and if it does not, then I’m assuming I’m in production. Not my favorite, though. haha

NODE_ENV should be there. Not sure where COMMIT_REF is setup.

Hmm NODE_ENV is undefined. I don’t use netlify-lambda or anything; just the built-in zip-it-and-ship-it.

Weird. Hopefully someone can shed some light on this!

A post was split to a new topic: API keys and environment variables on netlify