webpack-graphql-loader

1.0.2 verified Mon Apr 27 auth: no javascript

A webpack loader for .graphql files that provides schema validation, fragment imports, and supports both string and DocumentNode output. Version 1.0.2 is the latest stable release. The loader enables importing GraphQL queries, fragments, and schemas directly in JavaScript modules. It features an #import directive for composing GraphQL documents, optional minification, and integration with Apollo Client via DocumentNode output. Differentiators include built-in schema validation and unused fragment removal.

Common errors

error Module not found: Error: Can't resolve 'graphql' ↓

cause Missing graphql peer dependency.

fix

Run: npm install --save-dev graphql

error Validation failed: Cannot query field "foo" on type "Bar". ↓

cause The imported .graphql file contains a query that references fields not present in the schema.

fix

Ensure the schema.json is accurate and the query matches the schema definitions.

error You may need an additional loader to handle the result of these loaders. ↓

cause Webpack cannot parse the output of the loader when output is 'document' because it's an object, not a string.

fix

Ensure your webpack configuration handles JavaScript or set output to 'string'.

Warnings

gotcha The loader requires the graphql package as a peer dependency. Ensure graphql is installed in your project. ↓

fix Install graphql: npm install --save-dev graphql or yarn add --dev graphql

gotcha When using TypeScript, ts-loader is a peer dependency. You must have ts-loader installed for TypeScript support. ↓

fix Install ts-loader: npm install --save-dev ts-loader or yarn add --dev ts-loader

gotcha The loader uses #import statements within .graphql files. These are not standard GraphQL syntax and may cause issues with other tools. ↓

fix Use only within files processed by this loader; ensure other tools skip or are configured to ignore them.

deprecated The webpack 1.x syntax using 'loaders' array is deprecated. Use 'rules' array with 'use' for webpack 2+. ↓

fix Use module.rules instead of module.loaders, and 'use' with an object for options.

Install

npm install webpack-graphql-loader

yarn add webpack-graphql-loader

pnpm add webpack-graphql-loader

Imports

default
wrong
```
const query = require('./query.graphql')
```
correct
```
import query from './query.graphql'
```
Default import returns a string or DocumentNode depending on loader options

DocumentNode

wrong

import { DocumentNode } from 'webpack-graphql-loader'

correct

import { DocumentNode } from 'graphql'

For TypeScript, you may want to type the imported value

loader configuration

wrong

module.exports = { module: { loaders: [{ test: /\.graphql$/, loader: 'webpack-graphql-loader' }] } }

correct

module.exports = { module: { rules: [{ test: /\.graphql$/, use: [{ loader: 'webpack-graphql-loader', options: { validate: true, schema: './schema.json' } }] }] } }

Webpack configuration for the loader, not a JavaScript import

Quickstart

Configures webpack to load .graphql files with validation, minification, and DocumentNode output, including fragment imports.

// webpack.config.js
const path = require('path');
module.exports = {
  entry: './src/index.js',
  output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' },
  module: {
    rules: [
      {
        test: /\.graphql$/,
        use: [
          {
            loader: 'webpack-graphql-loader',
            options: {
              validate: true,
              schema: path.resolve(__dirname, 'schema.json'),
              output: 'document',
              minify: true
            }
          }
        ]
      }
    ]
  }
};

// src/query.graphql
#import "./fragments.graphql"
query User($id: ID!) {
  user(id: $id) {
    ...UserFields
  }
}

// src/fragments.graphql
fragment UserFields on User {
  name
  email
}

// src/index.js
import query from './query.graphql';
console.log(query); // DocumentNode object