shadcn/ui

Raypx 在独立的 packages/ui 包中管理 shadcn/ui 组件，主应用通过 @raypx/ui 引用。

components.json 配置

项目根目录的 components.json 定义了 shadcn/ui 的行为：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "base-lyra",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "packages/ui/src/styles/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "utils": "@raypx/ui/lib/utils",
    "ui": "@raypx/ui/components",
    "lib": "@/lib",
    "hooks": "@/hooks"
  }
}

关键配置说明：

字段	值	说明
`style`	`base-lyra`	使用 Lyra 样式变体
`rsc`	`false`	非 React Server Components 模式
`baseColor`	`neutral`	基础色为中性色
`cssVariables`	`true`	使用 CSS 变量控制主题
`iconLibrary`	`lucide`	图标库为 Lucide React

路径别名

由于组件位于 packages/ui 中，别名配置将 @raypx/ui 映射到对应的路径：

@raypx/ui/lib/utils -- 工具函数（如 cn()）
@raypx/ui/components -- shadcn/ui 组件目录

添加组件

向 packages/ui 添加新组件：

pnpm dlx shadcn@latest add button -c packages/ui

-c packages/ui 指定目标目录为 UI 包。

批量添加所有组件：

pnpm bump-ui

该命令等价于 pnpm dlx shadcn@latest add --all --overwrite -c packages/ui，会更新所有组件到最新版本。

更新命令

更新已安装的组件：

pnpm dlx shadcn@latest add --overwrite -c packages/ui

--overwrite 标志会覆盖已有组件文件，确保组件代码与最新版本一致。

更新组件前请检查是否有自定义修改，--overwrite 会丢失这些修改。建议在更新前提交当前代码。

导入模式

在主应用中导入 shadcn/ui 组件：

import { Button } from "@raypx/ui/components/button"

也可以通过根路径别名导入：

import { Button } from "@/components/ui/button"

这依赖于 tsconfig.json 中的路径映射配置。

工具函数

cn() 函数是 Tailwind CSS 类名合并工具，基于 clsx 和 tailwind-merge：

import { cn } from "@raypx/ui/lib/utils"

<div className={cn("px-4 py-2", isActive && "bg-primary")} />

自定义样式

修改主题颜色

编辑 packages/ui/src/styles/globals.css 中的 CSS 变量：

:root {
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  /* 修改变量值即可改变主题 */
}

颜色使用 OKLCH 色彩空间，可以使用 OKLCH 颜色选择器辅助选色。

修改圆角

在 @theme inline 中调整 --radius：

@theme inline {
  --radius: 0.625rem;
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  /* ... */
}

修改字体

替换字体导入和 CSS 变量即可更换字体：

@import "@fontsource-variable/your-font";

@theme inline {
  --font-sans: "Your Font Variable", sans-serif;
}

shadcn/ui

On this page