Netlify Environment Variables: The Cheat Codes of the Internet
We usually use Environment Variables as (global) variables, but did you know they can totally configure your environments as well?
Secret Globals, Global Secrets
Making use of Environment Variables on the Frontend
Because unintentionally leaking API tokens to clients is a Very Bad Thing, we have evolved best practices like prefixing environment variables with
GATSBY_. If you aren’t seeing an environment variable that you expected to see, this is probably the cause. Please check our Common Environment Variables Issues Guide on the Netlify Community site for self-serve help!
For hosted platforms like Netlify, we can also use environment variables to communicate from the build environment to the frontend, for the frontend to configure itself based on that information.
For example, Netlify automatically sets up Continuous Deployments when you link your Git repo. Imagine you are hosting documentation for open source. People often want to “view source” for your site. Instead of hardcoding the Git repo, you can simply reference
process.env.REPOSITORY_URL in your build process, and pass it to your static site generator of choice.
Granted you’re not going to change your Repo URL that often. But this is one of many examples. For example, if you use Deploy Previews to work in progress PR’s with collaborators and clients, you can check
process.env.CONTEXT === 'deploy-preview' and place a nice banner disclaiming that is not the production version of your site.
This kind of workflow with Environment Variables are key to how Netlify’s Split Testing feature works. By basing your A/B test on git workflow, there is no A/B testing API to learn - just make a new git branch and send traffic that way. On the frontend, if you check the
BRANCH context variable (again, with the caveat that some frontend frameworks may make you jump through some hoops to send this to the frontend).
Using Environment Variables to Vary your Environment
However, intelligent runtime environments can also configure themselves around your variables, which is a very nice way to offer backward compatibility or flagged functionality for different codebases that all work on the same exact platform. Let’s explore ideas for how this can work on Netlify:
Setting your Node Versions in Build Process and in Serverless Functions
To set your Node Version, you, well, set
This variable only affects your build environment. By default it is
v10.16.2 at time of writing, but if, for example, your build process requires node 8 or node 12, you can set it to
12 accordingly. You can also set a specific release version or use
.nvmrc if you like.
The other important environment you may wish to vary is your serverless functions. Netlify Functions are a nice development experience layer atop AWS Lambda. By default, Node Netlify Functions run in Node v8.10, but you can set
nodejs10.x (or any other valid AWS Lambda runtime name) to run in Node 10 for newer language features and better performance! (You can also set Go function environment versions with the build image.)
You can also set other important command line and environment versions as needed, for example
NPM_TOKEN (handy if you use a private npm instance).
Power User Features
There are even more environment variables available meant for introspection, debugging, and power users, for example the
HOME directory and
GOCACHE directory environment variables.
You can use variables like these to persist files between builds, to skip rebuilding files that already exist, and thereby massively speed up your static site builds by only building incremental new/changed pages. Check out
cache-me-outside for an example of how to do this.
You can reference the Big Fat List of Environment Variables here, and it will be fully documented in an upcoming version of the Netlify Docs.
What else can you do with these environment variables that we aren’t thinking about? Let me know!