Panda CSS 跨平台 Transformer 适配架构:Rust 核心如何接入 Vite、Rollup、webpack、Rspack 与 Turbopack
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,每个宿主适配器都遵循同一条五步契约:
- 挑选可转换的源码模块(通常通过文件扩展名与 include/exclude 过滤);
- 以源码文本和文件路径调用
@pandacss/transformer; - 返回改写后的代码及其 source map;
- 解析
@pandacss-internal/css内部导入; - 为 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)。
适配器形态分五步:
transform—— 通过共享钩子执行源码转换;resolveId—— 拦截@pandacss-internal/css;load—— 返回打包好的内部运行时(分隔符从项目配置中替换);- 保持 helper 失效逻辑无状态(stateless);
- 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前缀的.cssloader 把cssgen()注入到任何声明了 layer 的样式表内存中——这是 Vite.csstransform 的对应物。它会对每个源码文件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_transformcrate(见 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。
推荐发布顺序与验收标准
设计笔记给出的出货顺序:
@pandacss/transformer—— 已完成;- Vite 适配器 —— transform 钩子已完成,sandbox e2e 待补;
- Rollup 适配器;
- webpack 适配器;
- Rspack 验证;
- Rolldown 验证。
每个宿主只有在全部通过以下六项后才算完成:
- 源码转换快照(snapshot)测试;
- 内部模块解析测试;
- dead-import 清理测试;
- source map 校验;
- watch / 重建行为测试;
- 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 验收规则)。