📦 Rare UI 部署与使用教程

Rare UI 是一个基于 shadcn/ui 构建的罕见、可直接使用的 UI 组件和动画集合。它采用 Next.js、Tailwind CSS、TypeScript 和 Motion (用于动画) 构建。最大的特点是你“拥有”这些组件的代码：它们通过 shadcn CLI 直接安装到你的项目中，而不是作为 npm 包依赖，因此你可以自由地修改和重设样式。

⚙️ 部署前准备

在使用 Rare UI 之前，你的项目需要满足以下条件：

一个 Next.js 项目 (推荐使用 App Router)。
已配置 shadcn/ui：你的项目需要已经初始化了 shadcn/ui。如果还没有，请运行 npx shadcn@latest init 进行初始化。

🚀 使用方式一：直接安装组件（最常用）

你不需要克隆这个 GitHub 仓库。Rare UI 是一个 shadcn 注册表，你可以通过 shadcn CLI 直接将组件安装到你的项目中。

安装命令

在你的项目根目录下，运行以下命令：

1	npx shadcn@latest add swamimalode07/rare-ui/{组件名称}

将 {组件名称} 替换为你想要安装的组件名。

示例：安装 “Fluid Orb” 组件

1	npx shadcn@latest add swamimalode07/rare-ui/fluid-orb

此命令会自动将组件源码添加到你的 components/ui/ 目录下，并安装所需的依赖。

查看所有可用组件

你可以访问 rareui.com/components 浏览所有组件的实时预览、属性和使用方法。

💻 使用方式二：本地开发与贡献

如果你想查看所有组件的源码、本地预览或为 Rare UI 贡献代码，则需要克隆此仓库并本地运行。

1. 克隆并安装

1
2
3

git clone https://github.com/swamimalode07/rare-ui.git
cd rare-ui
npm install

2. 启动开发服务器

1	npm run dev

应用会在 http://localhost:3000 启动，你可以在这里预览所有组件及其交互。

3. 项目结构

components/ui/：所有组件源码存放于此。
registry.json：组件注册表配置文件，定义了每个组件在 shadcn CLI 中的元数据。

4. 构建注册表

如果你修改了组件或 registry.json，需要重新构建注册表输出，以便安装命令生效：

1	npm run registry:build

🧩 组件设计理念与特性

原生动画：所有组件都使用 Motion 库制作了流畅动画。
无障碍性：组件尊重用户的 prefers-reduced-motion 系统偏好设置，在用户要求减少动画时自动适配。
完全可控：安装后，组件代码完全属于你。你可以自由修改样式、逻辑或动画，无需担心库更新带来的破坏性变更。
TypeScript 支持：所有组件都是用 TypeScript 编写的，提供完整的类型提示。

❓ 常见问题

Q: 安装组件时提示 “Component not found”？
- A: 请检查组件名称是否拼写正确。所有可用组件的准确名称请参考 Rare UI 官网的列表。
Q: 我必须使用 Next.js 才能用这些组件吗？
- A: Rare UI 是一个为 Next.js + shadcn/ui 生态设计的注册表。虽然组件的核心逻辑是 React 代码，但直接迁移到其他 React 框架可能需要调整导入路径和构建配置。目前，最推荐且最简便的使用方式是在 Next.js 项目中。
Q: 安装组件后如何自定义样式？
- A: 组件安装到你的 components/ui/ 目录后，就是普通的 React 组件。你可以像修改自己写的任何组件一样修改它的 JSX、CSS 类名（Tailwind）或动画配置。