simple-react-app-kit/packages/ui/docs/zh-Hans/guide/setup.mdx

---
title: 项目配置
description: 配置 workspace 依赖、全局样式、Tailwind 扫描和 shadcn CLI。
order: 10
toc:
  - id: dependency
    title: 添加依赖
  - id: global-styles
    title: 全局样式
  - id: imports
    title: 显式导入
  - id: shadcn-cli
    title: shadcn CLI
  - id: browser-components
    title: 浏览器组件
  - id: verify
    title: 验证配置
---

## 添加依赖 {#dependency}

应用通过 workspace 协议引用 UI 包：

```json
{
  "dependencies": {
    "@workspace/ui": "workspace:*"
  }
}
```

仓库中的应用已经完成此配置。这个 package 当前是私有 workspace package，不需要从 npm 安装。

## 全局样式 {#global-styles}

在应用的全局 CSS 中导入一次：

```css
@import "@workspace/ui/globals.css";
```

该入口会加载 Tailwind CSS、shadcn 的 Tailwind 扩展、动画工具、Inter Variable 字体、语义颜色、圆角变量和基础样式。主题通过根节点上的 `.ui:light` 与 `.ui:dark` class 切换；组件代码不要自行复制这些变量。

`globals.css` 中的 `@source` 已覆盖本仓库的 `apps` 与组件目录。如果将 package 移到另一种目录结构，应同步调整扫描路径，否则生产构建可能缺少组件使用的 utility。

## 显式导入 {#imports}

package 没有聚合式 barrel。始终从具体子路径导入，便于追踪依赖并避免意外扩大客户端 bundle：

```tsx
import { Button } from "@workspace/ui/components/button"
import { SaveIcon } from "@workspace/ui/components/icon"
import { useIsMobile } from "@workspace/ui/hooks/use-breakpoint"
import { cn } from "@workspace/ui/lib/utils"
```

公开入口包括：

- `@workspace/ui/components/*`：组件与局部类型。
- `@workspace/ui/hooks/*`：断点和波纹交互。
- `@workspace/ui/locales`：支持的 locale 与消息 ID 类型。
- `@workspace/ui/locales/en-US`、`@workspace/ui/locales/zh-Hans`：消息与日历 locale。
- `@workspace/ui/globals.css`：全局样式。

## shadcn CLI {#shadcn-cli}

仓库根目录运行：

```sh
bunx shadcn@latest add button -c apps/web
```

应用和 UI package 的 `components.json` 使用同一套 `base-vega`、neutral、CSS variables、Lucide 词汇和 RTL 配置；别名会把生成文件放到 `packages/ui/src/components`。这与 shadcn 官方的 [monorepo 工作流](https://ui.shadcn.com/docs/monorepo)一致。

CLI 生成完成后必须检查 diff。生成器不知道本仓库的 Icones、国际化、波纹和 Popover 扩展，更新已有组件时可能覆盖本地适配。`components.json` 各字段的含义可参考[官方说明](https://ui.shadcn.com/docs/components-json)。

## 浏览器组件 {#browser-components}

多数交互组件依赖事件、Portal 或浏览器 API。使用 React Server Components 的消费端应从自身的客户端边界导入它们。本仓库配置为 `rsc: false`，组件文件不会统一插入框架专用指令；少数组件因自身需要显式包含 `"use client"`。

## 验证配置 {#verify}

修改组件或配置后运行：

```sh
bun run --cwd packages/ui typecheck
bun run lint
bun run format:check
```

如果改动涉及消费方式，再运行应用或文档的构建，确认 Tailwind 能扫描到新 class，并检查浅色、深色与 RTL。