Panda CSS 在 NX Monorepo 中的样式提取问题解决方案

问题背景

在使用 Panda CSS 与 NX Monorepo 集成时，开发者遇到了一个典型问题：在 React 应用程序中能够正确提取样式，但在 React 库中声明的样式却无法被提取。这种问题在组件库开发中尤为常见，因为开发者通常会将样式系统作为共享库，而组件则分布在不同的子库中。

问题分析

在提供的示例中，项目结构采用了 NX Monorepo 的标准布局：

• 样式系统位于 libs/styled-system
• UI 组件位于 libs/ui
• 应用位于 apps/web

问题表现为：

1. 在 apps/web 中直接使用的样式能够正确提取
2. 但在 libs/ui 中组件使用的样式无法被提取

根本原因

Panda CSS 的样式提取是基于配置文件中的 include 模式匹配的。在原始配置中，样式提取仅针对当前项目目录下的文件，没有包含其他库中的文件路径。

解决方案

正确的配置方法是将 Panda CSS 的配置文件移动到应用程序目录（apps/web），并调整 include 模式以包含库文件路径：

import { defineConfig } from '@pandacss/dev';

export default defineConfig({
  preflight: true,
  include: [
    '**/*.{ts,tsx}',
    "../../libs/ui/**/*.{ts,tsx}"  // 显式包含UI库路径
  ],
  exclude: [],
  theme: {
    extend: {},
  },
  importMap: '@panda-nx/styled-system',
  outdir: 'src',
});

关键配置说明

1. include 模式：必须显式包含所有需要使用 Panda CSS 的源代码路径，包括跨项目的库文件
2. importMap：指定样式系统的导入路径，保持与项目结构一致
3. outdir：指定生成的样式系统输出目录

最佳实践建议

1. 集中式配置：在 Monorepo 中，建议将 Panda CSS 配置放在应用程序层而非库层
2. 路径匹配：使用相对路径或 glob 模式确保覆盖所有需要提取样式的文件
3. 构建优化：考虑将样式提取作为构建流程的一部分，确保开发和生产环境一致性
4. 缓存策略：NX 的缓存机制可以与 Panda CSS 的增量构建结合，提高开发效率

总结

在 NX Monorepo 中使用 Panda CSS 时，正确的配置文件位置和路径匹配是确保样式提取正常工作的关键。通过将配置集中在应用程序层并正确设置包含路径，可以解决跨库样式提取的问题。这种架构既保持了样式系统的集中管理，又允许组件库的灵活分布，是大型项目开发的理想选择。