[!info] related notes

monorepo多包架构下的tailwind配置问题

📝 技术笔记：Monorepo 下 Tailwind v4 样式冲突与扫描修复

📌 问题背景

在 DailyUse 项目中，Web 和 Desktop 应用出现样式失效、层级混乱以及部分组件类名（Utility Classes）未生成的问题。

🔍 问题诊断与根因分析

1. 样式重复初始化 (Critical)

• 现象：CSS 层级 (@layer) 排序混乱，Preflight 样式被重置。
• 根因：@import "tailwindcss" 在导入链中出现了两次。
  • web/index.css 导入了 tailwindcss。
  • web/index.css 导入了 theme.css，而 theme.css 内部也导入了 tailwindcss。
• 后果：Tailwind v4 被初始化两次，导致基础样式冲突。

2. 隐式类名丢失 (Critical)

• 现象：ui-vue-shadcn 中的组件样式在构建后消失。
• 根因：Vite 模块图（Module Graph）无法自动追踪未设置 Alias 的子包源码。
  • web 项目引用 ui-vue-shadcn 的编译产物 (dist) 而非 .vue 源码。
  • 缺少 @source 指令，导致 Tailwind 扫描器忽略了 packages 目录下的组件源文件。

3. 运行时依赖错误 (Minor)

• 现象：生产环境可能抛出 clsx 或 tailwind-merge 找不到的错误。
• 根因：工具函数 cn() 依赖的包被错误地放置在 devDependencies 中。

---

🛠️ 解决方案

Fix 1: 规范化 CSS 导入顺序

从共享的 theme.css 中移除 @import "tailwindcss"。

原则：由应用入口（Consumer）负责初始化，共享包只负责定义变量、插件和层级扩展。

CSS

/* packages/ui-core/src/styles/theme.css */
/* ❌ 移除此处导入 */
@plugin "tailwindcss-animate";
@custom-variant dark (&:is(.dark *));
@theme { … }

Fix 2: 显式配置源码扫描路径 (@source)

在各应用入口 CSS 中明确指出需要扫描的源码目录，确保样式生成完整。

CSS

/* apps/web/src/styles/index.css */
@import "tailwindcss";
@import "../../../../packages/ui-core/src/styles/globals.css";

/* 💡 关键：显式指定跨包扫描路径 */
@source "../../../../packages/ui-core/src";
@source "../../../../packages/ui-vue-shadcn/src";
@source "../../../../packages/app-vue/src";

Fix 3: 修正依赖管理

将运行时必需的工具包移至 dependencies。

Package	Field	Note
clsx	dependencies	运行时处理类名合并
tailwind-merge	dependencies	运行时解决 Tailwind 类名冲突

---

✅ 修复验证

• 依赖更新：执行 pnpm install 同步 pnpm-lock.yaml。

• 开发环境：运行 npx nx run web:serve，控制台无 CSS 编译错误。

• 样式表现：

  • 暗黑模式选择器 @custom-variant dark 正常生效。
  • ui-vue-shadcn 组件样式完整加载。
  • 基础字体与背景色应用正确。

---

下一步建议：

如果你打算在 Desktop 端也全面同步这套修复，我可以帮你检查 apps/desktop 的 Vite 配置中是否也需要添加类似的路径别名（Alias）优化？

Related notes

• AI MOC
• Monorepo MOC