Maofeng
92 lines
3.2 KiB
Plaintext
92 lines
3.2 KiB
Plaintext
---
|
|
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。
|