@graphql-tools/webpack-loader

中文文档
8.1.0发布于 2026/10/26MITTypeScriptESM + CJS构建来源已验证近 30 天下载 82.6万

A set of utils for faster development of GraphQL tools

原始使用文档
文档目录3 节
  1. Options
  2. Importing GraphQL files
  3. Preprocessing queries and fragments

GraphQL Tools Webpack Loader

A webpack loader to preprocess GraphQL Documents (operations, fragments and SDL)

Slightly different fork of graphql-tag/loader.

npm install @graphql-tools/webpack-loader

How is it different from graphql-tag? It removes locations entirely, doesn't include sources (string content of imported files), no warnings about duplicated fragment names and supports more custom scenarios.

Options

  • noDescription (default: false) - strips descriptions from SDL documents. Has no effect on operations or fragments.
  • noEmptyNodes (default: false) - strips empty arguments, directives, and variableDefinitions from SDL documents. Has no effect on operations or fragments.
  • noLoc - accepted for compatibility. Location information is always stripped.
  • replaceKinds (default: false) - replaces "kind": "Document" strings in the emitted AST with Kind.DOCUMENT references from graphql/language/kinds.
  • esModule (default: false) - emit export default instead of module.exports. #import then reads the default export of the imported document.
  • importHelpers (default: false) - require useUnique from @graphql-tools/webpack-loader-runtime instead of inlining the helper.

Importing GraphQL files

To add support for importing .graphql/.gql files, see Webpack loading and preprocessing below.

Given a file MyQuery.graphql

query MyQuery {
  ...
}

If you have configured the webpack @graphql-tools/webpack-loader, you can import modules containing graphQL queries. The imported value will be the pre-built AST.

import MyQuery, { MyQuery as NamedMyQuery } from './query.graphql'

A file may contain more than one operation. The default export is the whole document. Each named operation and fragment is also exported under its GraphQL name, with only the fragments that operation uses:

# menuMutations.graphql
mutation deleteMenuMutation {
  deleteMenu {
    ...MenuFields
  }
}

mutation upsertMenuMutation {
  upsertMenu {
    id
  }
}

fragment MenuFields on Menu {
  id
  name
}
import { deleteMenuMutation, MenuFields, upsertMenuMutation } from './menuMutations.graphql'

A fragment brought in with #import is also exported under its GraphQL name from the importing file, after the imported definitions are appended.

@graphql-tools/jest-transform uses this loader, so the same named imports work in Jest. Operations in a multi-operation file must be named.

Preprocessing queries and fragments

Preprocessing GraphQL queries and fragments into ASTs at build time can greatly improve load times.

Webpack loading and preprocessing

Using the included @graphql-tools/webpack-loader it is possible to maintain query logic that is separate from the rest of your application logic. With the loader configured, imported graphQL files will be converted to AST during the webpack build process.

{
  loaders: [
    {
      test: /\.(graphql|gql)$/,
      exclude: /node_modules/,
      loader: '@graphql-tools/webpack-loader',
      options: {
        /* ... */
      }
    }
  ],
}

版本与发布记录

@graphql-tools/webpack-loader 共发布 664 个版本,首次发布于 2020/06/02;过去 12 个月发布了 153 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
8.1.0latest2026/10/2621 天前
8.1.0-rc-20261026131423-8fabaf53c1774b23fb7f57b7dadfe5d6b5213dacrc2026/10/2621 天前
8.1.0-alpha-20261026123108-071eb6cfddd27d23db13b9ffc9051c072334a401alpha2026/10/2621 天前
8.1.0-alpha-20261026122756-d820b8099b0a6fe9c218e6e0820ecc34b7e5daf52026/10/2621 天前
8.1.0-alpha-20261026121847-75fd8ee1b5baa57c5039f3d1805399a1e4f2d5102026/10/2621 天前
8.1.0-alpha-20261026031207-872f174b78389989102096bcfff633be6688b5502026/10/2621 天前

其他发布通道:canary → 6.2.4-alpha-dee550e0.0,beta → 6.5.0-alpha-e6320b00.0,alpha → 8.1.0-alpha-20261026123108-071eb6cfddd27d23db13b9ffc9051c072334a401,rc → 8.1.0-rc-20261026131423-8fabaf53c1774b23fb7f57b7dadfe5d6b5213dac。

关于 @graphql-tools/webpack-loader 的常见问题

@graphql-tools/webpack-loader 是什么?

A set of utils for faster development of GraphQL tools

如何安装 @graphql-tools/webpack-loader?

在项目目录运行 npm install @graphql-tools/webpack-loader,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:graphql(^16.0.0 || ^17.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@graphql-tools/webpack-loader 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@graphql-tools/webpack-loader 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@graphql-tools/webpack-loader 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.18.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@graphql-tools/webpack-loader 可以商用吗?

@graphql-tools/webpack-loader 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@graphql-tools/webpack-loader 的下载量有多少?

根据 npm 官方下载统计,@graphql-tools/webpack-loader 在 2026/10/17 – 2026/11/15 这 30 天内被下载 825,819 次,日均约 27,527 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@graphql-tools/webpack-loader 还在维护吗?

最新版本 8.1.0 发布于 2026/10/26(21 天前);至今共发布 664 个版本,其中过去 12 个月发布了 153 个;首次发布于 2020/06/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。