@graphox/babel-plugin

@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

Configuration	Initial Chunk	Per-Lazy-Chunk
Without plugin	~50KB+ (all AST)	~1KB
With plugin	~1KB	~1KB

Configuration Options

Option	Type	Required	Description
manifestPath	string	Yes*	Path to manifest.json generated by codegen
manifestData	object[]	Yes*	Inline manifest data (alternative to manifestPath)
outputDir	string	Yes	Directory containing generated files
graphqlImportPaths	string[]	No	Explicit import paths to treat as GraphQL entrypoints
emitExtensions	string	No	File extension for generated imports: "none" (default), "ts", "js", "dts"

*Either manifestPath or manifestData is required.

emitExtensions

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

Value	Result
"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.

When to Use

Build Tool	Recommended Plugin
React Native (Metro)	Babel
Webpack	Babel
Create React App	Babel
Storybook	Babel
rsbuild	Use SWC plugin
Turbopack/Next.js	Use SWC plugin

See Also

• SWC Plugin
• graphox CLI
• Configuration Guide