React Starter Kit UI 组件与主题体系实战:shadcn/ui + Tailwind CSS v4 的 Monorepo 落地指南
React Starter Kit UI 组件与主题体系实战:shadcn/ui + Tailwind CSS v4 的 Monorepo 落地指南
导读
本文聚焦 React Starter Kit 的 UI 与主题层:如何在 Monorepo 中组织 shadcn/ui(new-york 风格)组件、用 bun ui:* 命令维护组件库、基于 OKLCH CSS 变量与 Tailwind CSS v4 实现亮/暗双主题,并避免常见的导入、样式丢失与首屏白闪问题。读完你将掌握 packages/ui 与 apps/app 之间的组件归属原则、cn() 的类名合并机制、Jotai 驱动的主题状态流,以及一套可直接复制的主题定制与故障排查方案。
技术底座:shadcn/ui + Tailwind CSS v4
整个 UI 层建立在两条主线上:
- shadcn/ui(new-york 风格):组件不是以依赖包形式安装,而是通过 CLI 将源码直接写入仓库,由你完全掌控;
- Tailwind CSS v4:以 CSS-first 方式配置,通过
@import "tailwindcss"与@source声明扫描路径,取代了旧版的tailwind.config.js。
组件配置由 packages/ui/components.json 描述:style: "new-york"、cssVariables: true、iconLibrary: "lucide"、别名 @/components、@/lib/utils 等,是 shadcn CLI 生成代码时的依据。底层依赖包括 @radix-ui。
组件的两个家:归属原则决定架构边界
| 维度 | packages/ui/components/ |
apps/app/components/ |
|---|---|---|
| 内容 | shadcn/ui 原语——Button、Card 等 |
产品部件——AuthForm、UserMenu、NotFound 等 |
| 感知范围 | React、Radix、样式工具 | 路由、查询、会话、产品业务规则 |
| 维护方 | shadcn CLI(bun ui:add) |
你(手写) |
| 导入方式 | @repo/ui |
@/components/... |
判据只有一条:一个组件只有在"换个应用依然成立"时才放进 packages/ui。任何会伸手去拿路由、查询或会话的组件,都属于 apps/app/components(例如 auth-form.tsx、user-menu.tsx、sidebar-nav.tsx)。这样 packages/ui 保持纯净、可复用,而产品逻辑被隔离在应用层,不会污染共享库。
用 CLI 添加组件:命令、产物与两个坑
仓库根 package.json 提供了五个脚本,实际实现在 packages/ui/scripts:
bun ui:add button # 添加单个组件
bun ui:add dialog card select # 一次添加多个
bun ui:add --all # 添加 registry 中所有组件
bun ui:essentials # 添加精选入门组件集
bun ui:list # 列出已安装组件
bun ui:update # 从 registry 重新拉取已安装组件
以 add.ts 为例,其内部执行 bunx shadcn@latest add <组件> --yes,随后调用 formatGeneratedFiles() 用 Prettier 格式化生成的文件。从 package.json 的 scripts 可以看到 add/list/update/essentials 分别对应 scripts/add.ts、list.ts、update.ts、essentials.ts。
坑一:CLI 不会更新 barrel 导出
添加组件只写文件并格式化,不会触碰 packages/ui/index.ts 的导出。需要手动补一行:
// packages/ui/index.ts
export * from "./components/toggle-group";
否则 import { ToggleGroup } from "@repo/ui" 无法解析。当前该文件已导出 avatar、button、card、checkbox、dialog、input、label、radio-group、scroll-area、select、separator、skeleton、switch、textarea、toggle、toggle-group 以及 cn。
坑二:bun ui:update 会原地覆盖本地修改
CLI 生成物并不统一:部分组件仍输出 Context.Provider 与 useContext,而本项目 ESLint 配置要求使用 React 19 的新形式(<Context> 与 use())。因此更新前务必 git diff 审查,对本地改动做好取舍。
包结构速览
packages/ui/
├── components/ # 每组件一个文件
│ ├── button.tsx
│ ├── card.tsx
│ └── ...
├── hooks/
├── lib/
│ └── utils.ts # cn() 工具
├── scripts/ # CLI 工具(add、list、update、essentials)
├── components.json # shadcn CLI 配置——风格、别名、图标库
├── styles.css # 仅服务于 shadcn CLI;真实样式在应用中
├── index.ts # barrel 导出
└── package.json
两个关键细节:
@/lib/utils别名的"消费端解析"机制:CLI 生成的组件内部写import { cn } from "@/lib/utils"。该别名并不由packages/ui自己的 tsconfig 解析,而是由消费应用的配置解析——所以每个应用都必须保留一个再导出垫片,如 apps/app/lib/utils.ts 的export { cn } from "@repo/ui"。同理,包内组件互相引用必须用相对路径(./toggle),若照抄 CLI 的@/components/...形式会解析到应用里去,导致构建失败。- 单一入口:组件与
cn从包根统一再导出,应用只需从一个地方导入:
import { Button, Card, CardHeader, CardTitle, Input, cn } from "@repo/ui";
packages/ui/package.json 的 exports 字段还开放了子路径:./lib/utils、./components/*、./hooks/*、./lib/*,peerDependencies 要求 React 19.2.4+。
使用组件:以 Card 组合为例
shadcn/ui 的复合组件遵循"拼接而非继承"模式。以 Card 为例,其拆分为 Card、CardHeader、CardTitle、CardDescription、CardContent 等零件,直接组合即可:
import {
Card,
CardContent,
CardDescription,
CardHeader,
CardTitle,
} from "@repo/ui";
import type { ReactNode } from "react";
type FeatureCardProps = {
title: string;
description: string;
children: ReactNode;
};
export function FeatureCard({
title,
description,
children,
}: FeatureCardProps) {
return (
<Card>
<CardHeader>
<CardTitle>{title}</CardTitle>
<CardDescription>{description}</CardDescription>
</CardHeader>
<CardContent>{children}</CardContent>
</Card>
);
}
cn():条件类名与冲突消解
cn() 定义在 packages/ui/lib/utils.ts,本质是 clsx 与 tailwind-merge 的组合:
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
clsx负责条件拼接(falsy 值自动忽略);tailwind-merge负责冲突消解——后写的类胜出,所以cn("p-4", "p-6")得到"p-6"。
这带来一个关键能力:外部传入的 className 可以覆盖组件自身的默认样式,而不必与默认类在 specificity 上搏斗:
import { Button, cn } from "@repo/ui";
export function SaveButton({ isActive }: { isActive: boolean }) {
return (
<Button
className={cn(
"transition-colors",
isActive && "bg-primary text-primary-foreground",
)}
>
Save
</Button>
);
}
主题体系:OKLCH 变量 + @theme inline 映射
颜色即变量:改一处,全局跟随
主题颜色以 CSS 自定义属性定义在 apps/app/styles/globals.css,使用 OKLCH 颜色空间(对亮度的感知更均匀,插值更一致)。每个应用各持一套:apps/app 主应用一份,营销站 apps/web 保持一份镜像副本。核心变量摘录:
:root {
--radius: 0.625rem;
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
--destructive: oklch(0.577 0.245 27.325);
/* ... */
}
.dark {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
/* ... */
}
随后 apps/app/tailwind.config.css 用 @theme inline 将这些变量映射成 Tailwind 工具类对应的主题令牌:
@theme inline {
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
--radius-xl: calc(var(--radius) + 4px);
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
/* ... */
}
于是 bg-primary、text-muted-foreground 等工具类自动解析到变量。要换肤就改变量——所有引用它的工具类随之生效。
两个实战注意点:
- 令牌成对存在:
--primary是表面色,--primary-foreground是绘于其上的文字色。改动一个,必须检查另一个与之的可读性对比度; - 亮暗都要改:
:root与.dark两处需同步编辑——在纯白背景上可读的颜色,在近黑背景上往往不行。
暗色模式:dark 类变体
暗色模式通过自定义 Tailwind 变体,键控在 dark 类上:
/* apps/app/tailwind.config.css */
@custom-variant dark (&:is(.dark *));
apps/app 下还额外 @import "tw-animate-css",为 dialog、select 等提供进入/退出动画工具类——缺少它这些类不会生成任何 CSS,开合动画会直接消失(见 tailwind.config.css 的注释)。
主题状态机:Jotai atom,而非 React Context
dark 类由 apps/app/lib/theme.tsx 管理。整个设计有一个清晰的模型:用户持有 preference(light / dark / system),应用渲染 theme(只可能是 light 或 dark),theme 永远是派生的,而不是一份需要手工同步的状态。
import { useTheme } from "@/lib/theme";
function ThemeButton() {
const { theme, preference, setPreference } = useTheme();
return (
<button onClick={() => setPreference(theme === "dark" ? "light" : "dark")}>
{preference === "system" ? `System (${theme})` : preference}
</button>
);
}
源码中有几个值得细读的实现点:
- 三个 atom 的分工:
themePreferenceAtom(atomWithStorage持久化偏好,storage key 为"theme")、systemThemeAtom(atomWithLazy惰性读取prefers-color-scheme,并在订阅期间持续监听系统变化)、themeAtom(纯派生:preference === "system"时取系统主题,否则取偏好)。派生关系的完整逻辑见 theme.tsx。 - 健壮性处理:
themePreferenceAtom对getItem/setItem/subscribe都做了 try/catch 与值校验(toPreference),因为 localStorage 里什么脏数据都可能存在,且getOnInit: true会让读取在模块求值期就发生——若浏览器拒绝存储访问,未防护的读取会直接拖垮整个 bundle。 - atom 是私有实现细节:对外只暴露
useTheme(),其返回类型被显式写出,避免调用方触达 Jotai 的 setter 更新函数与RESET等持久化机制。 ThemeSync组件(theme.tsx)挂载在 apps/app/index.tsx 的StoreProvider内、应用根部,用useLayoutEffect把解析后的主题镜像到<html>:切换dark类、设置color-scheme属性(让滚动条、原生表单控件跟随)、并把--theme-color变量的值写进<meta name="theme-color">。而StoreProvider(lib/store.ts)为全应用所有 Jotai atom 提供统一的 store 根。
首屏防白闪:index.html 内联脚本
纯 React 方案的问题在于:主题在 bundle 加载完成后才落地,暗色用户会看到一帧白屏。解法是 apps/app/index.html 中一段内联脚本,在首次绘制前就把三件事定下来:
<script>
(() => {
let preference;
try {
preference = JSON.parse(localStorage.getItem("theme"));
} catch {
// Storage unavailable or corrupt – fall back to the OS setting.
}
const dark =
preference === "dark" ||
(preference !== "light" &&
matchMedia("(prefers-color-scheme: dark)").matches);
document.documentElement.classList.toggle("dark", dark);
document.documentElement.style.colorScheme = dark ? "dark" : "light";
if (dark) {
document
.querySelector('meta[name="theme-color"]')
.setAttribute("content", "#0f0f0f");
}
})();
</script>
这段脚本有意重复了 theme.tsx 的部分解析逻辑,且必须满足三条一致性约束:
- storage key 与 JSON 编码必须与
theme.tsx的atomWithStorage完全一致(否则偏好读不到); - 两处 hex 色值必须与 globals.css 中的
--theme-color保持一致(亮色#fafafa、暗色#0f0f0f)——因为此刻样式表尚未解析,脚本无法读取 CSS 变量,只能硬编码;注释里明确说明这是刻意为之; - site.manifest 中的
theme_color: "#fafafa"也必须同步(它只声明亮色,加载先于任何样式表)。
ThemeSync 在 React 挂载后接管,并补齐"内联脚本执行后、React 渲染前"这段时间内发生的系统或跨标签页主题变化。
切换器:直接用 ToggleGroup
主题切换 UI 直接复用单选的 toggle-group.tsx:单选的 ToggleGroup 天然携带 radio 语义与方向键导航,无需再手写键盘处理。
Tailwind 内容扫描:@source 与"完整类名"约束
Tailwind v4 通过扫描 @source 列出的文件来发现类名。主应用 tailwind.config.css 的扫描清单:
@import "tailwindcss";
@source "./lib/**/*.{js,ts,jsx,tsx}";
@source "./routes/**/*.{js,ts,jsx,tsx}";
@source "./components/**/*.{js,ts,jsx,tsx}";
@source "./index.html";
@source "./index.tsx";
@source "../../packages/ui/components/**/*.{ts,tsx}";
@source "../../packages/ui/lib/**/*.{ts,tsx}";
@source "../../packages/ui/hooks/**/*.{ts,tsx}";
注意:应用与共享包都必须列入,否则只出现在 packages/ui 里的类会被生产构建剔除。扫描是文本级的,Tailwind 只认完整类名字符串:bg-red-500 能被发现,而 `bg-${color}-500` 这种字符串插值拼出来的类名不会被识别——请改为维护完整的类名映射表。
故障排查速查表
@repo/ui 导入失败
组件可能未安装或未导出。先 bun ui:list 确认,再检查 packages/ui/index.ts 是否已添加对应导出行——bun ui:add 不会替你加。
开发环境正常、构建产物丢样式
类名所在文件不在任何 @source 覆盖范围内,或者类名由字符串插值拼装而成。参见上文"Tailwind 内容扫描"一节。
完全没有任何样式
检查 apps/app/index.tsx 是否导入了 ./styles/globals.css——这是样式管线的入口,缺失即全裸。
TypeScript 无法解析 @repo/ui
消费应用需要同时具备路径别名与项目引用,二者缺一不可:
{
"compilerOptions": {
"paths": { "@repo/ui": ["../../packages/ui"] }
},
"references": [{ "path": "../../packages/ui" }]
}
延伸阅读
- packages/ui/README.md:共享 UI 包的使用说明与组件清单
- apps/app/components:产品级组件(AuthForm、UserMenu、布局侧边栏等)的实际写法
- docs/frontend 与 docs/recipes/new-page.md:前端结构、表单与新增页面的配套指南
- packages/ui/styles.css 与 components.json:shadcn CLI 的配置与生成基础
- apps/web/styles/globals.css:营销站的主题变量镜像副本