@graphox/babel-plugin

中文文档
1.5.2发布于 2026/11/16MITTypeScriptCommonJS构建来源已验证近 30 天下载 2.4万

Babel plugin for Graphox codesplitting

原始使用文档
文档目录16 节
  1. Overview
  2. Why Use This Plugin?
  3. Installation
  4. Quick Start
  5. 1. Configure graphox
  6. 2. Run Codegen
  7. 3. Configure Babel
  8. Metro (React Native)
  9. Codesplitting Impact
  10. Multiple Projects
  11. Configuration Options
  12. emitExtensions
  13. Fragment Documents
  14. When to Use
  15. See Also
  16. License

@graphox/babel-plugin

Overview

Ensures GraphQL AST files are properly codesplit, preventing them from all ending up in the initial chunk.

Why Use This Plugin?

Codegen already generates AST files at compile time. The problem is bundler behavior:

Without plugin:

Initial chunk: ALL generated AST files (~50KB+)
Lazy chunks: empty or minimal

With plugin:

Initial chunk: ~1KB (just imports)
Lazy chunks: each operation in its chunk

Installation

pnpm add --save-dev @graphox/babel-plugin

Quick Start

1. Configure graphox

# graphox.yaml
output_dir: "__generated__"
projects:
  - schema: "schema.graphql"
    include: "src/**/*.{ts,tsx}"

2. Run Codegen

pnpm graphox codegen

3. Configure Babel

// babel.config.js
const path = require('path');

module.exports = {
  presets: ['@babel/preset-typescript'],
  plugins: [
    ['@graphox/babel-plugin', {
      manifestPath: path.resolve(__dirname, '__generated__/manifest.json'),
      outputDir: path.resolve(__dirname, '__generated__'),
      graphqlImportPaths: ['@/graphql']
    }]
  ]
};

Metro (React Native)

Metro uses Babel transformers under the hood. Configure in metro.config.js:

// metro.config.js
module.exports = {
  transformer: {
    babelTransformerPath: require.resolve('@graphox/babel-plugin'),
  },
};

For full compatibility, also configure in babel.config.js.

Codesplitting Impact

ConfigurationInitial ChunkPer-Lazy-Chunk
Without plugin~50KB+ (all AST)~1KB
With plugin~1KB~1KB

Multiple Projects

Register every output directory a build resolves against in one plugin entry, so imports that cross a project boundary can be rewritten:

['@graphox/babel-plugin', {
  outputs: [
    { outputDir: path.resolve(__dirname, '__generated__') },
    { outputDir: path.resolve(repoRoot, 'packages/catalog/graphql') },
  ],
}]

Within the package owning an output, documents are imported by relative path. Crossing a package boundary, the import goes through the package's public specifier instead, because a relative path would reach past its subpath exports:

// before
import { ProductCardFragmentDoc } from "@example/catalog/graphql";
// after
import { ProductCardFragmentDoc } from "@example/catalog/graphql/catalog.codegen";

That needs the owning package to export the files inside the output directory:

{
  "name": "@example/catalog",
  "exports": {
    "./graphql": "./graphql/index.ts",
    "./graphql/*": "./graphql/*"
  }
}

The specifier is inferred from the package's name and exports, with a warning naming the exact entry to add when the wildcard is missing. Inference only fires when exactly one exports subpath resolves to the output directory, so set importAlias explicitly for a package without a usable exports field.

Document names and sources may repeat across outputs — resolution is scoped to the entrypoint an import came from. Output directories must be distinct and must not nest.

Configuration Options

OptionTypeRequiredDescription
outputsobject[]Yes*One entry per project; see below
emitExtensionsstringNoFile extension for generated imports: "none" (default), "ts", "js", "dts"

Each entry in outputs:

OptionTypeRequiredDescription
outputDirstringYesDirectory containing generated files
manifestPathstringNoPath to manifest.json. Defaults to <outputDir>/manifest.json
manifestDataobject[]NoInline manifest data, used instead of manifestPath
graphqlImportPathsstring[]NoExtra import paths to treat as GraphQL entrypoints
importAliasstringNoPublic specifier for this output. Inferred from the package's name and exports
packageRootstringNoRoot of the package owning this output. Inferred as the directory of the nearest package.json

*The single-output form — those fields at the top level instead of inside outputs — is still accepted and behaves as a one-element outputs.

emitExtensions

Controls the file extension appended to generated import paths. Should match the emit_extensions setting in your graphox.yaml:

ValueResult
"none" (default)import { X } from "./file.codegen"
"ts"import { X } from "./file.codegen.ts"
"js"import { X } from "./file.codegen.js"
"dts"import { X } from "./file.codegen.d.ts"

Fragment Documents

When generate_ast_for_fragments: true is enabled in your config, fragment documents are also included in the manifest and will be properly rewritten by the plugin.

A fragment without a document, such as a @type_only one, is listed in the manifest by its source alone. The plugin replaces its graphql() call with {}, the value graphql.ts returns for it, so ResultOf<typeof Doc> still types it.

With graphql_tag_fallback: true, graphql.ts parses such a fragment at runtime instead, which the plugin cannot do. The fragment is then left out of the manifest, and the plugin fails the build on its graphql() call.

When to Use

Build ToolRecommended Plugin
React Native (Metro)Babel
WebpackBabel
Create React AppBabel
StorybookBabel
rsbuildUse SWC plugin
Turbopack/Next.jsUse SWC plugin

See Also

License

MIT — see LICENSE.

版本与发布记录

@graphox/babel-plugin 共发布 46 个版本,首次发布于 2026/02/26;过去 12 个月发布了 46 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
1.5.2latest2026/11/16今天
1.5.12026/11/16今天
1.5.02026/11/124 天前
1.4.12026/11/0115 天前
1.4.02026/10/2819 天前
1.3.02026/10/2621 天前

关于 @graphox/babel-plugin 的常见问题

@graphox/babel-plugin 是什么?

Babel plugin for Graphox codesplitting

如何安装 @graphox/babel-plugin?

在项目目录运行 npm install @graphox/babel-plugin,或使用 pnpm add / yarn add / bun add。

@graphox/babel-plugin 支持 TypeScript 吗?

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

@graphox/babel-plugin 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@graphox/babel-plugin 可以商用吗?

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

@graphox/babel-plugin 的下载量有多少?

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

@graphox/babel-plugin 还在维护吗?

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