Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


Using ENV variables inside of your Page Queries is not as easy as it might seem at first. This plugin handles injecting a whitelist of allowed ENV variables into your createPage context so that they can be used when making queries.

Note: Static Queries in components are NOT supported.

How to install

Overview of Steps:

  • Install Plugin as Dependency

  • Create .env files

  • Add plugin to config

  • Modify/Create PageQuery

Install Plugin as Dependency

npm install -D gatsby-plugin-pagenv


yarn add -D gatsby-plugin-pagenv

Create .env Files

The development .env file is required as a base.


From there, you will likely want to create a separate .env.* file where * is the name of your other environment. Such as .env.staging.


Add Plugin to Config

  plugins: {
      resolve: "gatsby-plugin-pagenv",
      options: {
        allowedVariables: [
            key: "INDEX_LOGO_IMAGE",
            type: "String", // Optional since String is default
            key: "INDEX_LOGO_IMAGE_WIDTH",
            type: "Int",

Modify/Create pageQuery

There are a couple important things to take note of.

You will pass the env variables you allowed into the query with a type annotation:

query ($INDEX_LOGO_IMAGE: String!)

Lastly, use the variable in your query somewhere:

(relativePath: { eq: $INDEX_LOGO_IMAGE }) {

When you put them together, it will look something like this:

export const pageQuery = graphql`
  query ($INDEX_LOGO_IMAGE: String!) {
    newPlaceholderImage: file(relativePath: { eq: $INDEX_LOGO_IMAGE }) {
      childImageSharp {
        fluid(maxWidth: 300) {

Available options

  • allowedVariables: [] - an array of objects containing the ENV variables you would like to be grabbed from process.env and their scalar types
  type: "Int",

You can find out more about GraphQL types here: https://graphql.org/learn/schema/#scalar-types

Passing Environment

By default, pagenv looks at the ENVIRONMENT env variable.


ENVIRONMENT=staging yarn build

If you would like to change the env variable name that pagenv looks for you can do so with PAGENV_ENVIRONMENT_VAR.



When do I use this plugin?


  • Loading mock data in Development

  • Changing image processing values to speed up Development

Examples of usage

You can see a full example within the examples/ folder of this repo. We will add more as more use cases are discovered.

How to run tests


How to develop locally


How to contribute

If you have unanswered questions, would like help with enhancing or debugging the plugin, it is nice to include instructions for people who want to contribute to your plugin.

© 2023 Gatsby, Inc.