@graphox/swc-plugin

Overview

Pre-built SWC plugin for Graphox codesplitting. This package bundles the WASM binary for easy use with rsbuild, Turbopack, or native SWC.

Prerequisites

Building the WASM plugin from source requires:

Rust toolchain (1.70+): rustup install stable
WASM target: rustup target add wasm32-wasip1
wasm-pack: cargo install wasm-pack
Node.js 18+
pnpm: corepack enable && corepack install -g pnpm@latest

For users of the pre-built package, only Node.js 18+ is required.

Installation

pnpm add @graphox/swc-plugin

Requirements

Node.js 18+
rsbuild, Turbopack, or native SWC

Usage

rsbuild Configuration

// rsbuild.config.ts
import { defineConfig } from '@rsbuild/core';
import { createSWCPlugin } from '@graphox/swc-plugin';
import path from 'path';

export default defineConfig({
  source: {
    alias: {
      '__generated__': path.resolve(__dirname, './__generated__'),
    },
  },
  tools: {
    swc: {
      jsc: {
        parser: {
          syntax: 'typescript',
          tsx: true,
        },
        experimental: {
          plugins: [
            createSWCPlugin({
              manifestPath: './__generated__/manifest.json',
              outputDir: './__generated__'
            })
          ],
        },
      },
    },
  },
});

Turbopack/Next.js Configuration

// next.config.js
import { createSWCPlugin } from '@graphox/swc-plugin';

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    turbo: {
      rules: {
        '*.{ts,tsx}': [
          {
            loader: 'next-swc-loader',
            options: {
              jsc: {
                parser: {
                  syntax: 'typescript',
                  tsx: true,
                },
                experimental: {
                  plugins: [
                    createSWCPlugin({
                      manifestPath: './__generated__/manifest.json',
                      outputDir: './__generated__'
                    })
                  ],
                },
              },
            },
          },
        ],
      },
    },
  },
};

module.exports = nextConfig;

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.

Local Development

You can override the WASM plugin path by setting the GRAPHOX_SWC_PLUGIN_PATH environment variable. This is useful for testing local builds of the Rust plugin without copying files.

export GRAPHOX_SWC_PLUGIN_PATH=$(pwd)/target/wasm32-wasip1/release/graphox_swc_plugin.wasm

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.

Building from Source

If you need to rebuild the WASM plugin:

# Install dependencies
pnpm install

# Build TypeScript only (requires pre-built WASM)
pnpm run build

# Build WASM only (requires Rust toolchain)
pnpm run build:wasm

# Build everything (TypeScript + WASM)
pnpm run build:all

# Run tests
pnpm test

JSPM