@graphox/swc-plugin

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

Graphox 的 SWC 插件: 重写 spholmql () 调用以引导生成的文档导入, 因此未使用的文档为树形

中文使用文档
文档目录17 节
  1. 概览
  2. 先决条件
  3. 安装
  4. 所需资源
  5. 主机版本
  6. 使用量
  7. 构建配置
  8. 下一个.js 配置
  9. 多个项目
  10. 跨项目进口
  11. 配置选项
  12. 地方发展
  13. 喷出量
  14. 分块文档
  15. 来源建筑
  16. 另见
  17. 许可证

@ graphox/ swc- 插件

概览

为 Graphox 编码预建的 SWC 插件 。 这个软件包将WASM二进制捆绑起来,以便于与rsbuild,Turbopack,或原生SWC一起使用.

先决条件

从源头构建 WASM 插件需要:

  • Rust工具链: 被钉入 rust-toolchain.toml —— 说 rustup 安装它, 编辑 wasm32-wasip1 目标,自动
  • 节点.js 22.13+(由pnpm 11要求)
  • 小时 11点: corepack enable && corepack install -g pnpm@latest

对于预建软件包的用户,只需要Node.js 18+.

安装

pnpm add @graphox/swc-plugin

所需资源

  • 节点.js 18+
  • rsbuilding、涡轮包装或原生SWC

主机版本

以 WASM 模块形式编译的插件船 swc_core,则 SWC 主机只运行它自己的 swc_core 这至少是新的。 每个主机嵌入 swc_core 因此,各层各有不同:

东道主最低
@swc/core1.15.0 (韩语)
@rspack/core,以及 @rsbuild/core 通过它2.2.0 (中文(简体) )

在旧主机上 建造失败 failed to invoke plugin,通常与 给主机命名提示 swc_core 版本。 更新主机——插件无法 工作围绕它.

使用量

构建配置

// 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__'
            })
          ],
        },
      },
    },
  },
});

下一个.js 配置

// 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;

设定 turbopack.root 财务报告和审定财务报表 root 到同一目录: 工作空间根 单列波 应用程序的目录。 Webpack 构建通过绝对路径和 忽略 root。 。 。 .

多个项目

模块对照多个输出目录解决 GraphQL 的工作空间 应全部登记在 一个 插件实例 :

graphox.createSWCPlugin({
  outputs: [
    { outputDir: path.resolve(__dirname, 'app/graphql') },
    { outputDir: path.resolve(repoRoot, 'packages/auth/graphql') },
    { outputDir: path.resolve(repoRoot, 'packages/catalog/graphql') },
  ],
})

每个产出一个实例是昂贵和不完整的:

  • 费用. SWC 将整个 AST 序列化到插件中并返回每个 每个模块上的插件,无论插件是否更改任何内容. 模块 完全属于一个输出, 因此在 N 例中, 其中 N− 1 个回合 每个单元都保证不操作.
  • 正确之处. 实例只知道自己的项目,所以不能重写 跨越工程边界的导入。 记录了每个产出 一起重定向从另一个项目的切入点导入的文档 直接在项目生成的文件.

跨项目进口

在拥有输出的软件包中,文档是通过相对路径导入的. 跨越包的边界, 相对路径会到达包的 子路径导出, 所以导入要通过软件包的公开显示符 相反:

// packages/storefront/graphql/storefront.codegen.ts, before
import { ProductCardFragmentDoc } from "@example/catalog/graphql";

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

这需要自有软件包导出其输出内的文件 目录, 而不仅仅是切入点 :

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

插件从软件包中推断出规格 name 财务报告和审定财务报表 exports,以及 警告在缺少通配符时指定要添加的确切条目。 推论是 故意保守主义 exports 子路径 解析到输出目录——如此设置 importAlias 明确用于软件包 没有 exports 字段,或仅通过捆绑者化名解决.

文件名称和来源可能在整个产出中重复。 界定两个项目 SetPriceMutationDocument,即使有相同的源文本,也很好: 解析范围为输入的入口,而不是搜索 跨越一个合并的地图.

输出目录必须明确,不得筑巢.

配置选项

选项类型需求说明
outputsobject[]对*每个项目一个条目;见下文。 首选单一产出领域
emitExtensionsstring没有生成导入的文件扩展名 : "none" (违约), "ts", (中文(简体) ), "js", (中文(简体) ), "dts"
rootstring没有目录主机的模块路径相对,对于一个通过相对路径的主机(Turbopack). 反对 cwd

每个条目 outputs数字 :

选项类型需求说明
outputDirstring对包含生成文件的目录
manifestPathstring没有路径 manifest.json默认为 <outputDir>/manifest.json
manifestDataobject[]没有内含显示数据, 而不是 manifestPath
graphqlImportPathsstring[]没有作为 GraphQL 切入点处理的额外导入路径
importAliasstring没有此输出的公开规格, 例如 . @example/catalog/graphql从包裹中推断出来的 name 财务报告和审定财务报表 exports
packageRootstring没有拥有此输出的软件包的根 。 推断为最近的目录 package.json

* 单一产出形式—— outputDir, (中文(简体) ), manifestPath, (中文(简体) ), manifestData, (中文(简体) ), graphqlImportPaths, (中文(简体) ), importAlias 财务报告和审定财务报表 packageRoot 在最高一级——仍然是 被接受并表现为一个单一要素 outputs。 。 。 .

地方发展

您可以通过设置 WASM 插件路径来覆盖 GRAPHOX_SWC_PLUGIN_PATH 环境变量。 这对测试 Rust 插件的本地建筑有用而无需复制文件 .

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

超接是一个绝对路径,Turbopack不加载.

喷出量

控制所生成导入路径所附加的文件扩展名。 应该符合 emit_extensions 设置 graphox.yaml数字 :

数值结果
"none" (默认)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"

分块文档

何时 generate_ast_for_fragments: true 在配置中被启用,片段文档也包含在运算表中,并由插件正确重写.

没有文件的碎片,例如: @type_only 一,单从其出处列出于清单. 插件替换其 graphql() 调用 {},该值 graphql.ts 返回它,所以 ResultOf<typeof Doc> 仍然按键.

与 graphql_tag_fallback: true, (中文(简体) ), graphql.ts 在运行时剖析这样的片段, 插件无法做到这一点 。 碎片则从清单中被忽略出,插件则无法在其上建构 graphql() 电话.

来源建筑

如果您需要重建 WASM 插件 :

# 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

另见

许可证

麻省理工学院——见 自由主义。 。 。 .

版本与发布记录

@graphox/swc-plugin 共发布 45 个版本,首次发布于 2026/02/26;过去 12 个月发布了 45 个版本。最新版本附带 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/swc-plugin 的常见问题

@graphox/swc-plugin 是什么?

Graphox 的 SWC 插件: 重写 spholmql () 调用以引导生成的文档导入, 因此未使用的文档为树形

如何安装 @graphox/swc-plugin?

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

@graphox/swc-plugin 支持 TypeScript 吗?

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

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

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@graphox/swc-plugin 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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