Real World Performance: lazy loading, optimizing media, faster analytics join us Wednesday

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 for more details.


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


Please file a bug if any issues occour.

© 2023 Gatsby, Inc.