React Starter Kit UI 组件与主题体系实战:shadcn/ui + Tailwind CSS v4 的 Monorepo 落地指南

原创2026-09-19 19:59:481,853 阅读
文章标签:后端前端

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

两个关键细节:

  1. @/lib/utils 别名的"消费端解析"机制:CLI 生成的组件内部写 import { cn } from "@/lib/utils"。该别名并不由 packages/ui 自己的 tsconfig 解析,而是由消费应用的配置解析——所以每个应用都必须保留一个再导出垫片,如 apps/app/lib/utils.ts 的 export { cn } from "@repo/ui"。同理,包内组件互相引用必须用相对路径(./toggle),若照抄 CLI 的 @/components/... 形式会解析到应用里去,导致构建失败。
  2. 单一入口:组件与 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 等工具类自动解析到变量。要换肤就改变量——所有引用它的工具类随之生效。

两个实战注意点:

  1. 令牌成对存在:--primary 是表面色,--primary-foreground 是绘于其上的文字色。改动一个,必须检查另一个与之的可读性对比度;
  2. 亮暗都要改::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 的部分解析逻辑,且必须满足三条一致性约束:

  1. storage key 与 JSON 编码必须与 theme.tsx 的 atomWithStorage 完全一致(否则偏好读不到);
  2. 两处 hex 色值必须与 globals.css 中的 --theme-color 保持一致(亮色 #fafafa、暗色 #0f0f0f)——因为此刻样式表尚未解析,脚本无法读取 CSS 变量,只能硬编码;注释里明确说明这是刻意为之;
  3. 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" }]
}

延伸阅读

登录后查看全文
react-starter-kit