Panda CSS 跨平台 Transformer 适配架构:Rust 核心如何接入 Vite、Rollup、webpack、Rspack 与 Turbopack

原创2026-10-09 12:20:142,195 阅读
文章标签:前端构建工具开发工具

Panda CSS 跨平台 Transformer 适配架构:Rust 核心如何接入 Vite、Rollup、webpack、Rspack 与 Turbopack

Panda CSS 的源码转换(css() / pattern / recipe / JSX style props → 类名字符串)由 Rust 核心 pandacss_transform 负责语义,@pandacss/transformer 充当薄薄的 JS 门面,而每个构建平台(Vite、Rollup、Rolldown、webpack、Rspack、Turbopack)只通过一个"宿主适配器"接入这一统一契约。本文基于仓库 design-notes/transformer/platform-support.md 的设计笔记,逐平台拆解适配器的钩子形态、内部模块解析、watch/失效模型与当前落地状态,并结合 @pandacss/vite、@pandacss/transformer 的真实源码给出实现级证据。读完你将对"如何给一个 Rust 核心的 CSS 引擎接入任意 bundler"形成一套可复用的架构认知,也能准确判断各平台适配器的能力边界与验收标准。

总体设计:Rust 拥有语义,JS 门面拥有绑定,宿主只拥有平台 API

整个跨平台方案的分工一句话可以概括为:Rust 拥有 transform 语义,@pandacss/transformer 是 JS 门面,每个 bundler 适配器只负责把这一契约映射到各自的模块解析、watch 与源码转换 API 上。

转换后的源码会导入内部运行时模块,例如:

import { cx as __pcx } from '@pandacss-internal/css'

特殊的 recipe 场景还可能从同一模块导入 attachRecipe as __pr 或 memoRecipe as __pm。宿主需要把 @pandacss-internal/css 解析成一个内部模块 ID,并返回由 @pandacss/transformer 提供的打包好的运行时源码。这里的关键约束是:源码里的导入写法在所有宿主上完全一致,只有内部解析后的 ID 是宿主原生的(例如 Vite 下是 \0pandacss:internal:css,见 runtime/internal/ids.ts 中 INTERNAL_CSS_IMPORT 与 INTERNAL_CSS_RESOLVED_ID 的定义)。

这套分层的直接动机是防止每个 bundler 各自重新实现一份 transform 规划器。设计笔记 design-notes/transformer/README.md 里明确写到:如果把真正的 planner 长期留在 JS 里,就等于在 compiler 旁边再造一个 compiler;而 transform 语义放回 Rust 后,parse、提取、token 解析、JSX 匹配与诊断这些 compiler 已经拥有的能力全部可以复用。

支持矩阵:六大宿主一次看清

宿主 Transform 钩子形态 内部模块形态 Watch / 失效模型 状态
Vite plugin transform virtual module dev server module graph + file watcher shipped(@pandacss/vite)
Rollup plugin transform virtual module plugin watchChange + emitted asset shipped(@pandacss/rollup)
Rolldown 原样运行 Rollup 插件 virtual module plugin watchChange 通过 Rollup 插件验证
webpack pre loader + 编排插件 virtual module(unplugin) loader dependencies + watchRun shipped(@pandacss/webpack)
Rspack webpack 兼容的 loader/plugin 路径 synthetic module 或 alias loader dependencies + compiler watch 计划通过 webpack 形态落地
Turbopack turbopack.rules loader(仅 JS) data URL(无 virtual module) loader dependencies 被 CSS 聚合问题阻塞

矩阵背后是一个朴素的判断:集成点的差异太大,无法用一个包通吃所有平台——Vite/Rollup 是 plugin hooks + virtual modules;webpack/Rspack 是 loader/plugin 组合;Turbopack 只有 loader、没有 virtual module,CSS 必须以内联 data URL 方式随 JS 传输。所以最终形态是:一个 Rust 核心、一个 JS 门面(@pandacss/transformer)、若干小而专的宿主适配器。

共享宿主契约:每个适配器都要做且只做五件事

无论面向哪个 bundler,每个宿主适配器都遵循同一条五步契约:

  1. 挑选可转换的源码模块(通常通过文件扩展名与 include/exclude 过滤);
  2. 以源码文本和文件路径调用 @pandacss/transformer;
  3. 返回改写后的代码及其 source map;
  4. 解析 @pandacss-internal/css 内部导入;
  5. 为 transform 上报的额外文件注册 watch 依赖。

边界划分非常严格:Rust 拥有语义,JS 门面拥有绑定形态,宿主适配器只拥有宿主 API。宿主包不应该决定 transform 语义、不应该决定 helper 行为、不应该重复实现 dead-import cleanup、更不应该维护自己的 rewrite planner。

这套契约在代码里确实被抽象成了可直接复用的钩子。@pandacss/transformer 的 hooks.ts 导出了 createPandaSourcePluginHooks,一次性返回 resolveId / load / transform 三件套:

  • resolveId 拦截 @pandacss-internal/css 并映射为 INTERNAL_CSS_RESOLVED_ID;
  • load 对内部解析 ID 返回打包好的运行时源码(分隔符从 compiler 的 config 中解析);
  • transform 通过 runSourceTransform 执行转换,并把 result.dependencies 中上报的依赖逐一注册到宿主的 watch 体系(ctx.addWatchFile?.(dep),见 hooks.ts)。

@pandacss/transformer 还通过 plugin.ts 暴露了一个可选的 unplugin 包装 pandaTransformer,为 Rollup / webpack 风格的宿主直接提供 vite、webpack、rollup、esbuild、rspack、rolldown 各框架出口(index.ts)。unplugin 内部对 webpack/rspack 做了 Vue 单文件组件的 query 剥离处理(stripVueBlockQuery)。

Vite:当前最完整的适配器参考实现

状态与适配器形态

@pandacss/vite 已经在 transform、resolveId、load 三个钩子中直接调用 @pandacss/transformer 的 createPandaSourcePluginHooks。CSS-root 处理和 HMR 留在 Vite 包内(源码见 packages/vite/src/index.ts)。

适配器形态分五步:

  1. transform —— 通过共享钩子执行源码转换;
  2. resolveId —— 拦截 @pandacss-internal/css;
  3. load —— 返回打包好的内部运行时(分隔符从项目配置中替换);
  4. 保持 helper 失效逻辑无状态(stateless);
  5. compiler 来自 configResolved 阶段创建的 Panda driver。

当前内部解析 ID:

\0pandacss:internal:css

映射关系:

  • 源码导入:@pandacss-internal/css
  • 内部解析 ID:\0pandacss:internal:css

在 Vite 的实现里,插件的 transform 选项是默认关闭的:pandacss() 只做 CSS 注入、codegen 和 HMR,只有显式传入 pandacss({ transform: true }) 才会顺带改写源码(见 index.ts 中 transform?: boolean 的注释与 index.ts 的 sourceHooks 条件创建逻辑)。

Watch 行为

内部运行时没有任何动态状态,所以它本身不需要失效。但被转换的源码文件仍然需要 Panda 的 watch 行为:源码文件、配置文件,以及未来跨文件 transform 依赖。Vite 侧的处理集中在 hotUpdate:区分 design-system 文件、配置文件与源码文件,分别走 syncDesignSystemFileChange、driver.reload()(重跑 codegen + parseFiles)与 driver.applyChange,再通过 invalidateRoots 使模块图中的样式根失效;CSS 根文件则在 transform 钩子里注册 addWatchFile(index.ts)。

Rollup:复用 Vite 虚拟模块模型,自行交付样式资产

@pandacss/rollup 已发布。它通过 @pandacss/transformer 的 rollup unplugin 复用 Vite 的虚拟模块模型(resolveId / load / transform),外加一个小的编排插件(见 packages/rollup/src/index.ts 中 pandaTransformer.rollup({...}) 的调用):

  • pandaTransformer.rollup() 负责源码转换与 @pandacss-internal/css 模块;
  • buildStart 阶段运行 codegen 与 parseFiles;watchChange 增量并入编辑;
  • generateBundle 把样式表作为 Rollup asset 输出——因为 Rollup 本身没有 CSS 管线,样式表的交付由插件自己负责。

设计笔记给出了已验证的清单:css() / token() / patterns / recipes 内联、运行时模块干净打包、source map 链回原始源码、watch 重建产出新的 CSS。

Rolldown:不新增包,直接原样跑 Rollup 插件

Rolldown 的目标是与 Rollup 插件兼容,因此没有 @pandacss/rolldown 包——同一套 resolveId / load / transform / emitFile / generateBundle 表面在 Rolldown 下原样可用。差异只在于:Rolldown 自己用 OXC 编译 TS/JSX,所以配置文件里不再需要 esbuild 和 node-resolve。

设计笔记列出了在未修改的 Rollup 插件上验证过的三条出货规则:

  • helper 解析——@pandacss-internal/css 正常打包,没有悬空导入;
  • source map——v3 格式,映射回转换前的原始源码;
  • watch 重建——一次样式编辑触发重建并重新产出 CSS(约 20ms)。

范围说明:适配独立运行的 Rollup 与 Rolldown,以及 Rolldown 的库打包器 tsdown。由 Rolldown 驱动的 Vite 运行的是 Vite 插件,因此仍然留在 @pandacss/vite,不归这里管。另外,Rolldown 维护的 string_wizard 正是 pandacss_transform 用于编辑与 source map 的库,这只影响 printer 选型,不影响宿主契约。

webpack:loader 优先的适配器

@pandacss/webpack 以 loader 优先的形态发布。早期计划假设需要 alias 支持的自定义模块,但实际落地发现不需要——共享的 unplugin 已经处理了运行时模块:

  • pandaTransformer.webpack() 改写源码并解析 @pandacss-internal/css(走虚拟模块,而不是 alias);
  • 一个 pre 前缀的 .css loader 把 cssgen() 注入到任何声明了 layer 的样式表内存中——这是 Vite .css transform 的对应物。它会对每个源码文件 addDependency,因此源码一改动就会重建样式表,开发模式 HMR 不需要写盘;
  • 插件在 beforeCompile 阶段构建 driver,通过 watchRun 增量并入编辑;driver 通过自己的 fs 读取变更文件。

已在 Next.js(webpack 模式)上实测:next build 产出正确样式表,next dev 对样式编辑做 HMR。用户需要在自己的 globals.css 中保留 @layer …; 声明。

一个重要的使用前提:Next.js 16 默认使用 Turbopack,存在 webpack 配置时会构建失败,因此在 Turbopack 适配器落地前,withPandaCss 用户必须显式运行 next dev --webpack / next build --webpack。

Turbopack:卡点不在转换,而在 CSS 交付

Turbopack 适配器尚未构建,原因是硬骨头不在 transform 本身,而在 CSS 交付。Turbopack 没有插件 API,只有通过 turbopack.rules 配置的 loader(经 loader-runner 运行),约束如下:

  • loader 必须返回 JavaScript——不支持产出 CSS / asset 的 loader;
  • 选项必须是纯数据——不能传函数,不能 require() 模块;
  • 没有虚拟模块、没有 emitFile、没有 resolve(要用 getResolve);addDependency 和 getOptions 可用。

所以 webpack 的插件机制不能照搬,@pandacss-internal/css 也无法作为虚拟模块解析。参考 next-yak 的做法:它的 SWC transform 把提取出的 CSS 编码成 data:text/css;base64,… 导入,交给 Turbopack 的原生 CSS 管线消费——无虚拟模块,loader 返回 JS。

Panda 的难点在于:next-yak 的 CSS 是逐组件的,每个模块一个 data URL 很自然;而 Panda 的 CSS 是全应用级原子化、分层、去重的——按文件拆分 data URL 会导致原子类在各处重复、丢失层(layer)顺序。因此 CSS 聚合策略是首先要解决的设计问题。另外,SWC 插件也帮不上忙:Panda 的引擎是 OXC + 原生 NAPI,而 SWC 插件是 SWC-AST + Wasm 且没有 fs,CSS 聚合问题依然悬而未决。

Rspack:先复用 webpack 形态,遇到真不兼容再 fork

Rspack 以 webpack 插件与 loader 兼容为目标。设计上的决策很干脆:先实现(现已发布的)webpack 适配器形态,只有在真实不兼容处才 fork 出独立实现。这与 @pandacss/transformer 暴露 rspack 框架出口(index.ts)的方向一致——尽量共享,少造轮子。

为什么不做"一个宿主包通吃所有平台"

集成点的差异实在太大:

  • Vite 与 Rollup:plugin hooks + 虚拟模块;
  • Rolldown:原样运行 Rollup 适配器;
  • webpack 与 Rspack:loader / 插件组合;
  • Turbopack:只有 loader、无虚拟模块——CSS 必须内联在 JS 里(data URL)。

如果先把 planner 写死在 Vite 里再到处复制,Vite 的修复不会自动作用于 webpack,webpack 的边界用例也不会自动改善 Rollup,测试覆盖还会按宿主碎片化。而"一个 transformer 包 + 薄宿主适配器"能让正确性工作在整个生态共享。设计笔记在 design-notes/transformer/README.md 中把这条原则进一步落实为:bundler 包依赖 @pandacss/transformer,而不是反过来。

内部模块通用流程与源码级细节

设计笔记给出了端到端的模块流动:

source code
  → Rust transformer plans rewrites + which symbols to import
  → @pandacss/transformer returns rewritten code + map
  → host adapter intercepts @pandacss-internal/css
  → host adapter maps to internal module ID
  → host adapter returns bundled runtime source

各环节在仓库中的落点:

  • Rust 侧:语义规划、string_wizard 编辑应用、dead-import cleanup、helper 导入同步都收在 pandacss_transform crate(见 crates/pandacss_transform/src)。Rust 在输出发生变化时发出 v3 source map。
  • JS 门面:@pandacss/transformer 的 transform.ts 定义了 shouldTransform——默认只处理 .js/.mjs/.cjs/.ts/.tsx/.jsx(含 c/m 前缀变体),并额外放行不带 query 的 .svelte、.vue、.astro;include / exclude 正则用于进一步过滤。transformSource 把 helper.cx(true/false/'auto')与 targets(css/patterns/recipes/tokens/jsx)翻译成原生 binding 选项。
  • 转换判定:runSourceTransform 在 !changed && diagnostics.length === 0 时返回 null,避免无谓地让宿主替换模块内容(hooks.ts)。
  • 依赖上报:TransformResult.dependencies 专为 transform 发现的外部 watch 边预留——同文件转换通常返回空数组,但 webpack/Rspack 需要显式注册依赖,未来的跨文件常量解析也需要 watch 边。transformer 只上报路径,由宿主适配器转成 this.addDependency、addWatchFile 等宿主原生原语。

运行时无状态:HMR 与 watch 的共同前提

内部运行时在所有宿主上都是无状态的:没有隐藏全局变量、没有运行时注册。缓存与失效全部留在 bundler、适配器与 compiler 缓存里。这一设计让 HMR 简化成纯粹的模块失效问题,也让 Rollup/Vite 的虚拟模块 load 可以安全地每模块图只返回一次源码,并保证跨编辑保持无状态。

helper(cx)本身也遵循"窄而稳"的原则:它只拼接 transformer 能产出的形状(字符串、假值、嵌套数组),跳过假值与 ""、压平嵌套数组、保留顺序与重复项、不排序、不合并冲突、不分析类语义;别名 __pcx 避免与用户代码里的 cx 绑定冲突。只有文件实际用到的符号才会被注入——只含静态类的文件不会多出一个 import。运行时以语法与标识符压缩、但不做空白压缩的方式预构建,因为 esbuild 在去除空白时会丢掉 /* @__PURE__ */ 注释,而应用 bundler 需要该注释才能 tree-shake 未使用的 cx。

推荐发布顺序与验收标准

设计笔记给出的出货顺序:

  1. @pandacss/transformer —— 已完成;
  2. Vite 适配器 —— transform 钩子已完成,sandbox e2e 待补;
  3. Rollup 适配器;
  4. webpack 适配器;
  5. Rspack 验证;
  6. Rolldown 验证。

每个宿主只有在全部通过以下六项后才算完成:

  1. 源码转换快照(snapshot)测试;
  2. 内部模块解析测试;
  3. dead-import 清理测试;
  4. source map 校验;
  5. watch / 重建行为测试;
  6. bundle-size fixture 检查。

这些验收项在 design-notes/transformer/test-matrix.md 中被展开为分层测试矩阵:Rust transformer 单元测试(快照、bailout、helper 决策、动态策略)、native/wasm binding 边界测试、宿主适配器集成测试与 bundle-size fixtures。集成测试层面还要求"等价输入下,native Rust transformer 在 Vite、Rollup、webpack、Rspack 上产出相同结果"——这正是"一个 Rust 核心 + 薄适配器"架构的验收体现。另一个关键验收线是 bundle 体积:helper 模式必须在重复动态 className 场景下真正减少构建产物字节数,而纯静态场景不能因为引入了 helper 支持而变大。

关键要点回顾

  • 架构主轴:Rust(pandacss_transform)定语义 → JS 门面(@pandacss/transformer)定绑定与运行时 → 宿主适配器只接平台 API。
  • 统一内部模块:@pandacss-internal/css 在所有宿主源码中写法一致,解析后的内部 ID 由宿主各自决定(Vite 为 \0pandacss:internal:css)。
  • 五步宿主契约:选模块 → 调 transform → 返回代码 + map → 解析内部模块 → 注册 watch 依赖。
  • 当前状态:Vite、Rollup、webpack 已发布;Rolldown 通过原样运行 Rollup 插件验证;Rspack 计划复用 webpack 形态;Turbopack 被 CSS 聚合策略阻塞,且需要依赖虚拟模块方案不可行而以内联 data URL 为方向。
  • 使用前提:宿主插件的源码改写默认关闭(pandacss({ transform: true }));Next.js 16 用户当前需 --webpack 标志运行。

要深入跟进,推荐继续阅读同一设计笔记目录下的 design-notes/transformer/README.md(transform 三阶段模型、TransformerOptions 与 helper 契约)与 design-notes/transformer/test-matrix.md(完整测试矩阵与 bundle 验收规则)。

登录后查看全文
panda