Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import query from './query.graphql'
✗ const query = require('./query.graphql')
Default import returns a string or DocumentNode depending on loader options
DocumentNode
✓ import { DocumentNode } from 'graphql'
✗ import { DocumentNode } from 'webpack-graphql-loader'
For TypeScript, you may want to type the imported value
loader configuration
✓ module.exports = { module: { rules: [{ test: /\.graphql$/, use: [{ loader: 'webpack-graphql-loader', options: { validate: true, schema: './schema.json' } }] }] } }
✗ module.exports = { module: { loaders: [{ test: /\.graphql$/, loader: 'webpack-graphql-loader' }] } }
Webpack configuration for the loader, not a JavaScript import
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
Errors
Common errors & fixes
Module not found: Error: Can't resolve 'graphql'
Missing graphql peer dependency.
fixRun: npm install --save-dev graphql
Validation failed: Cannot query field "foo" on type "Bar".
The imported .graphql file contains a query that references fields not present in the schema.
fixEnsure the schema.json is accurate and the query matches the schema definitions.
You may need an additional loader to handle the result of these loaders.
Webpack cannot parse the output of the loader when output is 'document' because it's an object, not a string.
fixEnsure your webpack configuration handles JavaScript or set output to 'string'.
Audit
Dependencies
graphqlrequiredPeer dependency for schema validation and DocumentNode creation
ts-loaderoptionalPeer dependency for TypeScript support