手把手教你如何为 shadcn-vue 贡献代码

首先，我们要明确目标：你想迁移哪个组件？

第一步，去 shadcn-vue 的 GitHub Issue 页面看看是否已有人提出。如果找到了，为避免有多人进行相同的迁移，可以在评论区积极认领这个组件。如果没有，就自己创建一个新 Issue，简要说明想迁移的组件，等待社区确认。

确认后，我们就可以开始行动了！

迁移前的准备

在写代码之前，先把环境理清楚，可以省去后续不少麻烦。

Fork 并克隆仓库：访问 shadcn-vue 仓库，点击 Fork 到你的 GitHub 账号下。然后将它克隆到本地，并创建一个新的分支，例如 feat/add-marker-component。
（可选）参考官方源码：为了方便对照，你可以把 shadcn/ui 官方仓库也克隆到本地。这样在迁移时能随时参考 React 源码的实现细节。
安装依赖：在项目根目录运行 pnpm install，确保所有依赖都安装正确。

核心步骤：组件迁移

组件迁移主要分三部分：文档、组件代码和样式。我们以迁移 Marker 组件为例。

1. 编写组件文档

文档是组件的门面。在 apps/v4/content/docs/components 目录下新建一个 marker.md 文件。

shadcn-vue 的文档基于 Nuxt Content 构建，你可以在文件中使用 Vue 组件和 Markdown 语法来展示示例。

我们使用如下代码包裹示例代码，在文档页面它的表现形式是会展示组件效果并有源码展示。

::component-preview
---
name: MarkerDemo # 这里需要你在 `apps/v4/components/demo` 中有同名的组件
class: style-luma # 这里是附加到组件展示时的样式，一般不需填写。
---
::

2. 迁移组件代码

这是最核心的一步。我们需要在两个地方创建组件：

apps/v4/registry/new-york-v4/ui/marker/：这个目录存放无头（Headless） 组件。它只负责逻辑和基本结构，不要包含任何 cn- 开头的预设样式类，所有样式通过 Tailwind 的工具类直接写在模板中。
apps/v4/registry/bases/reka-ui/ui/marker/：这个目录存放带预设样式的组件。你需要在这里重复实现该组件，并为其应用不同的预设样式。

迁移小贴士：
将 React 的 className 替换为 Vue 的 :class 绑定。
将 React 的事件处理（如 onClick）替换为 Vue 的 @click。
React中使用 base ui 或者 radix 作为底层，vue这里我们使用 reka-ui。

3. 适配预设样式

为了让组件在不同的预设风格下都能完美显示，你还需要在 apps/v4/registry/styles/ 目录下，找到对应的预设 CSS 文件（如 style-luma.css），并添加以 cn- 开头的自定义样式类。这些类会被第二步中的预设样式组件所使用。

验证与提交

迁移完成后，我们需要验证一下是否一切正常：

启动本地文档，查看各种效果是否正常。
生成注册文件：在项目根目录运行 pnpm run registry:build。这个命令会自动扫描你的组件，并生成相应的 JSON 配置文件，这是 pnpm dlx shadcn-vue@latest add 命令能够工作的基础。
运行检查：确保项目能正常构建（pnpm run build），并且代码符合规范（pnpm run lint）。
提交代码：请务必只提交与当前组件相关的文件改动，主要包括：
- 新增的组件文件（apps/v4/registry/...）
- 新增的文档文件（apps/v4/content/...）
- 由 registry:build 生成的 JSON 文件

创建 Pull Request

完成以上步骤后，将你的分支推送到 GitHub，然后在 shadcn-vue 主仓库创建一个 Pull Request（PR）。

在 PR 描述中，清晰地说明你迁移了哪个组件，并附上相关的 Issue 链接。之后，耐心等待维护者的 Review 即可。他们会给出修改建议，在一切符合要求后，你的代码就会被合并到 dev 分支，并最终出现在 shadcn-vue 官网上！

结语

Vue 生态的繁荣，离不开像你一样愿意主动分享和付出的人。如果你在贡献过程中遇到任何问题，欢迎在评论区留言，我们一起探讨。期待你的第一个 PR！🎉