Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


Plugin for gatsby to handle environment variables with ease.

  • Handle empty strings
  • Strip out GATSBY_ prefix


Install with npm or yarn

npm install gatsby-plugin-config dotenv -S

In absolute top of your gatsby-config.js:

// Initialize dotenv
  path: `.env.${process.env.NODE_ENV}`, // or '.env'

// And then you can use the config in gatsby-config.js
const config = require('gatsby-plugin-config');


Import the plugin with import

import config from 'gatsby-plugin-config';

GATSBY variables

Variables prefixed with GATSBY_ are accessiable from the client side by default. This plugin allows you to query them without the prefix.

// process.env.GATSBY_API_URL

Empty variables

You don’t have to match empty variables anymore like this:

if (process.env.GATSBY_IS_STAGING && process.env.GATSBY_IS_STAGING !== '') {
    // do something

You can now just do:

if (config.IS_STAGING) {
    // you're done


Usage in files without module system (like gatsby-config / gatsby-node etc.)

const config = require('gatsby-plugin-config').default;

module.exports = {
  siteMetadata: {
    title: config.SITE_TITLE,


You can keep separate dotenv files for each environment in the project root. See https://github.com/motdotla/dotenv for more details.


The format is simply .env.${process.env.NODE_ENV}


Please file a bug if any issues occour.

© 2023 Gatsby, Inc.