@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