Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


npm version GitHub issues GitHub license

A Gatsby plugin for loading .graphql and .gql files with the help of graphql-tag/loader.

This is for:

Loading queries for browser runtime GraphQL operations, such as with Apollo Client.

This is not for:

Loading queries used at build time.

For more information on the distinction between runtime vs. build time, see the Gatsby docs.


The graphql-tag package needs to be installed alongside this plugin. To install both:

Using Yarn

yarn add gatsby-plugin-graphql-loader graphql-tag

Using NPM

npm i gatsby-plugin-graphql-loader graphql-tag


Add the plugin to gatsby-config.js:

// In your gatsby-config.js
plugins: [`gatsby-plugin-graphql-loader`];

Now you can import .graphql and .gql files directly into your components.


A working example is show in this GitHub repository.

Suppose you have src/queries/get-comments-by-first-name.gql which contains the following query:

# get-comments-by-first-name.gql
query getUserComments($firstname: String!) {
  users(where: { firstname_eq: $firstname }) {
    comments {

In a component file (say, /src/components/user-info.js), import the query from the .gql file, make the query with Apollo Client, and render out the information returned by the query:

// user-info.js
import React from "react";
import { useQuery } from "@apollo/react-hooks";
import GET_USER_COMMENTS from "../queries/get-comments-by-first-name.gql";

const UserInfo = ({ firstname }) => {
  const { data, loading, error } = useQuery(GET_USER_COMMENTS, {
    variables: { firstname }
  const [user] = !loading && !error ? data.users : [null];
  if (error) {
    return <p>Error Querying Data</p>;
  return (
    error ||
    (!loading && (
        <h3>First Name</h3>
        <h3>Comments</h3>{" "}
          {user.comments.map(({ text }, index) => (
            <li key={`${text.slice(0, 10)}-${index}`}>{text}</li>

export { UserInfo };
© 2023 Gatsby, Inc.