GraphQL Loader for Webpack

A webpack loader for .graphql query documents with first class support for schema validation and fragments definitions. graphql-loader works great with thunder, apollo-client, and anywhere you might want to provide a GraphQL query document in the frontend.

Installation

yarn add --dev webpack-graphql-loader # or npm install --save-dev webpack-graphql-loader

You will also need to install a copy of graphql, which is a peer dependency of this package.

yarn add --dev graphql # or npm install --save-dev graphql

Configuration

Add webpack-graphql-loader to your webpack configuration:

module.exports = {
  // ...
  module: {
    rules: [ // or "loaders" for webpack 1.x
      { test: /\.graphql?$/, loader: 'webpack-graphql-loader' }
    ]
  }
}

Specifying options

You can also pass options to the loader via webpack options:

module.exports = {
  // ...
  module: {
    rules: [ // or "loaders" for webpack 1.x
      {
        test: /\.graphql?$/,
        use: [
          {
            loader: 'webpack-graphql-loader',
            options: {
              // validate: true,
              // schema: "./path/to/schema.json",
              // removeUnusedFragments: true
              // etc. See "Loader Options" below
            }
          }
        ]
      }
    ]
  }
}

Loader Options

schema (string) (default="")

The location of your graphql introspection query schema JSON file. If used with the validate option, this will be used to validate imported queries and fragments.

validate (boolean) (default=false)

If true, the loader will validate the imported document against your specified schema file.

output ("string" | "document") (default="string")

Specifies whether or not the imported document should be a printed graphql string, or a graphql DocumentNode AST. The latter is useful for interop with graphql-tag.

minify (boolean) (default=false)

If true and the output option is string, the loader will strip comments and whitespace from the graphql document strings. This helps to reduce bundled code size.

removeUnusedFragments (boolean) (default=false)

If true, the loader will remove unused fragments from the imported document. This may be useful if a query is importing fragments from a file, but does not use all fragments in that file. Also see this issue.

Import statements in .graphql files

The loader supports importing .graphql files from other .graphql files using an #import statement. For example:

query.graphql:

#import "./fragments.graphql"

query {
  ...a
  ...b
}

fragments.graphql:

fragment a on A {}
fragment b on A {
  foo(bar: 1)
}

In the above example, fragments a and b will be made available within query.graphql. Note that all fragments in the imported file should be used in the top-level query, or the removeUnusedFragments should be specified.