@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: pinned in
rust-toolchain.toml—rustupinstalls it, and thewasm32-wasip1target, automatically - Node.js 22.13+ (required by pnpm 11)
- pnpm 11:
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
Host versions
The plugin ships as a WASM module compiled against a specific swc_core, and an
SWC host only runs it if its own swc_core is at least as new. Each host embeds
swc_core on its own schedule, so the floors differ:
| host | minimum |
|---|---|
@swc/core | 1.15.0 |
@rspack/core, and @rsbuild/core through it | 2.2.0 |
On an older host the build fails with failed to invoke plugin, usually with a
hint naming the host's swc_core version. Upgrade the host — the plugin cannot
work around it.
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__'
})
],
},
},
},
},
});
Next.js Configuration
// next.config.mjs
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { createSWCPlugin } from '@graphox/swc-plugin';
const appDir = path.dirname(fileURLToPath(import.meta.url));
// Turbopack passes the plugin each module's path relative to this directory:
// here the root of a workspace two levels above the app
const root = path.join(appDir, '..', '..');
/** @type {import('next').NextConfig} */
const nextConfig = {
turbopack: { root },
experimental: {
swcPlugins: [
createSWCPlugin({
outputs: [{ outputDir: path.join(appDir, '__generated__') }],
root,
}),
],
},
};
export default nextConfig;
Set turbopack.root and root to the same directory: the workspace root in a
monorepo, the app's directory otherwise. Webpack builds pass absolute paths and
ignore root.
Multiple Projects
A workspace whose modules resolve GraphQL against several output directories should register them all in one plugin instance:
graphox.createSWCPlugin({
outputs: [
{ outputDir: path.resolve(__dirname, 'app/graphql') },
{ outputDir: path.resolve(repoRoot, 'packages/auth/graphql') },
{ outputDir: path.resolve(repoRoot, 'packages/catalog/graphql') },
],
})
One instance per output is expensive and incomplete:
- Cost. SWC serializes the whole AST into the plugin and back for every plugin on every module, whether or not the plugin changes anything. A module belongs to exactly one output, so with N instances, N−1 of those round-trips per module are guaranteed no-ops.
- Correctness. An instance only knows its own project, so it cannot rewrite an import that crosses a project boundary. With every output registered together, a document imported from another project's entrypoint is redirected straight at that project's generated file.
Cross-project imports
Within the package that owns an output, documents are imported by relative path. Crossing a package boundary, a relative path would reach past the package's subpath exports, so the import goes through the package's public specifier instead:
// packages/storefront/graphql/storefront.codegen.ts, before
import { ProductCardFragmentDoc } from "@example/catalog/graphql";
// after
import { ProductCardFragmentDoc } from "@example/catalog/graphql/catalog.codegen";
That requires the owning package to export the files inside its output directory, not just the entrypoint:
{
"name": "@example/catalog",
"exports": {
"./graphql": "./graphql/index.ts",
"./graphql/*": "./graphql/*"
}
}
The plugin infers the specifier from the package's name and exports, and
warns naming the exact entry to add when the wildcard is missing. Inference is
deliberately conservative — it only fires when exactly one exports subpath
resolves to the output directory — so set importAlias explicitly for a package
with no exports field, or one resolved only through bundler aliases.
Document names and sources may repeat across outputs. Two projects defining
SetPriceMutationDocument, even with identical source text, is fine:
resolution is scoped to the entrypoint an import came from rather than searched
across a merged map.
Output directories must be distinct, and must not nest.
Configuration Options
| Option | Type | Required | Description |
|---|---|---|---|
outputs | object[] | Yes* | One entry per project; see below. Preferred over the single-output fields |
emitExtensions | string | No | File extension for generated imports: "none" (default), "ts", "js", "dts" |
root | string | No | Directory the host's module paths are relative to, for a host that passes relative ones (Turbopack). Resolved against cwd |
Each entry in outputs:
| Option | Type | Required | Description |
|---|---|---|---|
outputDir | string | Yes | Directory containing generated files |
manifestPath | string | No | Path to manifest.json. Defaults to <outputDir>/manifest.json |
manifestData | object[] | No | Inline manifest data, used instead of manifestPath |
graphqlImportPaths | string[] | No | Extra import paths to treat as GraphQL entrypoints |
importAlias | string | No | Public specifier for this output, e.g. @example/catalog/graphql. Inferred from the package's name and exports |
packageRoot | string | No | Root of the package owning this output. Inferred as the directory of the nearest package.json |
*The single-output form — outputDir, manifestPath, manifestData,
graphqlImportPaths, importAlias and packageRoot at the top level — is still
accepted and behaves as a one-element outputs.
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
The override is an absolute path, which Turbopack does not load.
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.
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.
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
See Also
License
MIT — see LICENSE.