Gatsby developers can use environment variables to provide values that need to be distinct across development environments. They are most commonly used to obfuscate certain information that may be sensitive and should not be exposed to others.
Some environments require different information to customize behavior in those environments. Others, for security reasons, need to ensure certain sensitive credentials like access tokens and configuration values aren’t exposed to the public. Regardless of their use, the environment variables we have in our local development environment need to be provided to the production environment, or other hosted environments, in a private and secure way.
There are two types of environment variables that are commonly used by Gatsby developers in their implementations:Project environment variablesThese are environment variables that dictate behavior in disparate environments and need to be defined in particular places, (such as a local development environment or remote production environment), in order to pass critical values to the site in each respective environment.Operating system–level environment variablesWe’ve seen a few examples throughout this app of OS-level environment variables, which accompany command-line executions as part of a build or deployment command. In Node.js, for instance, it’s common to prefix commands with definitions of environment variables where those environment variables need to be introduced as arguments, as we’ll see in the next section.
Both of these types of variables require special handling by Gatsby, which provides two environments out of the box in its framework. Though Gatsby can support additional environments, these two are the most commonly required:Development environmentGatsby considers any situation in which you run the gatsby develop command to be the development environment for its purposes.Production environmentRunning gatsby build or gatsby serve locally or in a hosted solution instantiates a production environment in Gatsby terms.
The two types of environment variables are only accessible for use during build-time compilation, when Node.js is running. Because no environment variable is exposed at runtime (since Gatsby is fundamentally an SSG), Gatsby needs to retrieve those environment variables and embed them into the client-side JavaScript bundle that it produces. In Gatsby’s internals, this is handled by the DefinePlugin plugin in Webpack.
Upon their availability in Gatsby’s client-side code, both project and OS-level environment variables can be accessed through the process.env global variable in Node.js. Because these environment variables are embedded only during build-time compilation, updating them requires you to restart the development server, or to perform a site rebuild, for the modifications to take effect.
NOTE
It’s possible in Gatsby to set up additional environments with a bit of additional work, such as arbitrary staging and test environments for needs such as quality assurance (QA). For more information, consult the Gatsby documentation’s guide to creating additional environments, with a real-world example involving Gatsby’s Google Analytics plugin.
Leave a Reply