shadcn-vue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn-vue

Quick Start (3 Minutes)

快速开始（3分钟）

For Vue Projects (Vite)

适用于Vue项目（Vite）

1. Initialize shadcn-vue

1. 初始化shadcn-vue

bash

npx shadcn-vue@latest init

During initialization:

Style:
```
New York
```
or
```
Default
```
(cannot change later!)
Base color:
```
Slate
```
(recommended)
CSS variables:
```
Yes
```
(required for dark mode)

bash

npx shadcn-vue@latest init

初始化过程中:

样式：
```
New York
```
或
```
Default
```
（初始化后无法更改！）
基础颜色：
```
Slate
```
（推荐）
CSS变量：
```
Yes
```
（暗色模式必需）

2. Configure TypeScript Path Aliases

2. 配置TypeScript路径别名

json

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

json

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

3. Configure Vite

3. 配置Vite

typescript

// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import tailwindcss from "@tailwindcss/vite"; // Tailwind v4
import path from "path";

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

typescript

// vite.config.ts
import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import tailwindcss from "@tailwindcss/vite"; // Tailwind v4
import path from "path";

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

4. Add Your First Component

4. 添加你的第一个组件

bash

npx shadcn-vue@latest add button

bash

npx shadcn-vue@latest add button

Quick Reference

快速参考

Need	Command or file
Initialize project	`npx shadcn-vue@latest init`
Add component	`npx shadcn-vue@latest add button`
Add multiple components	`npx shadcn-vue@latest add button card dialog`
Build registry JSON	`npx shadcn-vue@latest build`
Generate component docs	`npx tsx scripts/generate-shadcn-components.ts`
Enable CSS variables	`components.json` → `tailwind.cssVariables: true`
Add registry namespace	`components.json` → `registries` map
Opencode MCP init	`npx shadcn-vue@latest mcp init --client opencode`
Codex MCP config	`~/.codex/config.toml` with `mcp_servers.shadcn`

需求	命令或文件
初始化项目	`npx shadcn-vue@latest init`
添加组件	`npx shadcn-vue@latest add button`
添加多个组件	`npx shadcn-vue@latest add button card dialog`
构建注册表JSON	`npx shadcn-vue@latest build`
生成组件文档	`npx tsx scripts/generate-shadcn-components.ts`
启用CSS变量	`components.json` → `tailwind.cssVariables: true`
添加注册表命名空间	`components.json` → `registries` 映射
Opencode MCP初始化	`npx shadcn-vue@latest mcp init --client opencode`
Codex MCP配置	`~/.codex/config.toml` 中配置 `mcp_servers.shadcn`

Bundled Resources

内置资源

Templates (

templates/

```
quick-setup.ts
```
- Complete setup guide for Vue/Nuxt with examples (190 lines)

References (

references/

```
cli.md
```
- CLI commands and options
```
mcp.md
```
- MCP setup, client configs, prompts
```
theming.md
```
- Theming and
```
cssVariables
```
```
error-catalog.md
```
- All 7 documented issues with solutions (267 lines)
```
component-examples.md
```
- All 50+ component examples with code
```
dark-mode-setup.md
```
- Complete dark mode implementation guide
```
data-tables.md
```
- Data tables with TanStack Table

Component Documentation (

components/

```
references/components.md
```
- Index of all shadcn-vue components
```
components/<component>.md
```
- Individual component documentation with installation, usage, and examples

Official Documentation:

shadcn-vue Docs: https://shadcn-vue.com
Reka UI Docs: https://reka-ui.com
GitHub: https://github.com/radix-vue/shadcn-vue

模板 (

templates/

```
quick-setup.ts
```
- 适用于Vue/Nuxt的完整搭建指南及示例（190行）

参考文档 (

references/

```
cli.md
```
- CLI命令及选项
```
mcp.md
```
- MCP搭建、客户端配置、提示信息
```
theming.md
```
- 主题定制与
```
cssVariables
```
```
error-catalog.md
```
- 所有7个已记录问题及解决方案（267行）
```
component-examples.md
```
- 50+个组件示例及代码
```
dark-mode-setup.md
```
- 完整暗色模式实现指南
```
data-tables.md
```
- 搭配TanStack Table的数据表格

组件文档 (

components/

```
references/components.md
```
- 所有shadcn-vue组件索引
```
components/<component>.md
```
- 单个组件文档，包含安装、使用及示例

官方文档:

shadcn-vue文档: https://shadcn-vue.com
Reka UI文档: https://reka-ui.com
GitHub: https://github.com/radix-vue/shadcn-vue

When to Load References

何时加载参考文档

Load these references based on the task:

Load
references/error-catalog.md
when:
- User encounters "component not found" or import errors
- Setup commands fail or configuration issues arise
- Tailwind CSS variables or TypeScript paths broken
- Trigger phrases: "not working", "error", "fails to", "broken"
Load
references/components.md
when:
- User asks what components are available (names, categories, status)
- User needs to add/use a component and wants the correct install/import paths
- You need to confirm a component exists before recommending a custom build
Load
references/component-examples.md
when:
- User asks "how do I implement [component]?"
- Need copy-paste examples for specific components
- Building forms, tables, navigation, or data display
- Trigger phrases: "example", "how to use", "implement", "code sample"
Load
references/cli.md
when:
- User asks how to run the CLI (
```
init
```
  ,
```
add
```
  ,
```
update
```
  ) or what prompts mean
- Need the exact command/flags for installing one or more components
- Troubleshooting CLI-related issues (registry, paths, overwrites)
Load
references/dark-mode-setup.md
when:
- Implementing dark mode / theme switching
- User mentions Vue 3 + Vite, Nuxt, or Astro setup
- Need composable patterns for theme management
- Trigger phrases: "dark mode", "theme", "light/dark", "color scheme"
Load
references/theming.md
when:
- User wants to customize theme tokens via CSS variables (
```
cssVariables
```
  ,
```
:root
```
  ,
```
.dark
```
  )
- Need to wire Tailwind to CSS-variable-based colors and radii
- Setting up/adjusting design tokens (colors, radius, typography) for shadcn-vue
Load
references/mcp.md
when:
- Setting up MCP server for opencode, Codex, Cursor, VS Code
- Configuring registries in
```
components.json
```
- Troubleshooting missing components or registry namespaces
- Trigger phrases: "MCP", "opencode", "codex", "cursor", "registry"
Load
references/data-tables.md
when:
- Building sortable/filterable/paginated tables
- User mentions TanStack Table or
```
DataTable
```
- Trigger phrases: "data table", "table", "tanstack", "sorting", "pagination"

根据任务加载对应的参考文档：

加载
references/error-catalog.md
当:
- 用户遇到“组件未找到”或导入错误
- 搭建命令失败或出现配置问题
- Tailwind CSS变量或TypeScript路径失效
- 触发关键词: “无法工作”、“错误”、“失败”、“失效”
加载
references/components.md
当:
- 用户询问可用组件（名称、分类、状态）
- 用户需要添加/使用组件并获取正确的安装/导入路径
- 你需要确认组件是否存在再推荐自定义构建
加载
references/component-examples.md
当:
- 用户询问“如何实现[组件]？”
- 需要特定组件的可复制示例
- 构建表单、表格、导航或数据展示
- 触发关键词: “示例”、“如何使用”、“实现”、“代码示例”
加载
references/cli.md
当:
- 用户询问如何运行CLI（
```
init
```
  、
```
add
```
  、
```
update
```
  ）或提示信息含义
- 需要安装单个或多个组件的精确命令/标志
- 排查CLI相关问题（注册表、路径、覆盖）
加载
references/dark-mode-setup.md
当:
- 实现暗色模式/主题切换
- 用户提及Vue 3 + Vite、Nuxt或Astro搭建
- 需要主题管理的组合式模式
- 触发关键词: “暗色模式”、“主题”、“亮色/暗色”、“配色方案”
加载
references/theming.md
当:
- 用户想要通过CSS变量（
```
cssVariables
```
  、
```
:root
```
  、
```
.dark
```
  ）自定义主题令牌
- 需要将Tailwind与基于CSS变量的颜色和圆角关联
- 为shadcn-vue设置/调整设计令牌（颜色、圆角、排版）
加载
references/mcp.md
当:
- 为opencode、Codex、Cursor、VS Code搭建MCP服务器
- 在
```
components.json
```
  中配置注册表
- 排查组件缺失或注册表命名空间问题
- 触发关键词: “MCP”、“opencode”、“codex”、“cursor”、“注册表”
加载
references/data-tables.md
当:
- 构建可排序/可筛选/分页的表格
- 用户提及TanStack Table或
```
DataTable
```
- 触发关键词: “数据表格”、“表格”、“tanstack”、“排序”、“分页”

Critical Rules

重要规则

Always Do

务必执行

✅ Run
init
before adding components

Creates required configuration and utilities
Sets up path aliases

✅ Use CSS variables for theming (

cssVariables: true

)

Enables dark mode support
Flexible theme customization

✅ Configure TypeScript path aliases

Required for component imports
Must match
```
components.json
```
aliases

✅ Keep components.json in version control

Team members need same configuration
Documents project setup

✅ 添加组件前先运行
init

创建所需配置和工具
设置路径别名

✅ 使用CSS变量进行主题定制 (

cssVariables: true

)

支持暗色模式
灵活的主题定制

✅ 配置TypeScript路径别名

组件导入必需
必须与
```
components.json
```
中的别名匹配

✅ 将components.json纳入版本控制

团队成员需要相同配置
记录项目搭建信息

Never Do

切勿执行

❌ Don't change
style
after initialization

Requires complete reinstall
Reinitialize in new directory instead

❌ Don't mix Radix Vue and Reka UI v2

Incompatible component APIs
Use one or the other

❌ Don't skip TypeScript configuration

Component imports will fail
IDE autocomplete won't work

❌ Don't use without Tailwind CSS

Components are styled with Tailwind
Won't render correctly

❌ 初始化后不要更改
style

需要完全重新安装
建议在新目录中重新初始化

❌ 不要混合使用Radix Vue和Reka UI v2

组件API不兼容
二选一使用

❌ 不要跳过TypeScript配置

组件导入会失败
IDE自动补全无法工作

❌ 不要脱离Tailwind CSS使用

组件使用Tailwind样式
无法正确渲染

Common Mistakes

常见错误

Running
```
add
```
before
```
init
```
and missing
```
components.json
```
.
Forgetting to enable the MCP server in the client UI/config.
Mis-typed registry namespaces (
```
@namespace/component
```
).
Using CSS variable classes without
```
tailwind.cssVariables: true
```
.

未运行
```
init
```
就执行
```
add
```
，导致缺少
```
components.json
```
。
忘记在客户端UI/配置中启用MCP服务器。
注册表命名空间输入错误（
```
@namespace/component
```
）。
未设置
```
tailwind.cssVariables: true
```
就使用CSS变量类。

CLI Commands Reference

CLI命令参考

init Command

init命令

bash

undefined

bash

undefined

Initialize in current directory

在当前目录初始化

npx shadcn-vue@latest init

Initialize in specific directory (monorepo)

在指定目录初始化（单体仓库）

npx shadcn-vue@latest init -c ./apps/web

undefined

npx shadcn-vue@latest init -c ./apps/web

undefined

add Command

add命令

bash

undefined

bash

undefined

Add single component

添加单个组件

npx shadcn-vue@latest add button

Add multiple components

添加多个组件

npx shadcn-vue@latest add button card dialog

Add all components

添加所有组件

npx shadcn-vue@latest add --all

undefined

npx shadcn-vue@latest add --all

undefined

diff Command

diff命令

bash

undefined

bash

undefined

Check for component updates

检查组件更新

npx shadcn-vue@latest diff button

undefined

npx shadcn-vue@latest diff button

undefined

mcp Command

mcp命令

bash

undefined

bash

undefined

Initialize MCP for specific client

为特定客户端初始化MCP

npx shadcn-vue@latest mcp init --client opencode npx shadcn-vue@latest mcp init --client codex npx shadcn-vue@latest mcp init --client cursor npx shadcn-vue@latest mcp init --client vscode

---

npx shadcn-vue@latest mcp init --client opencode npx shadcn-vue@latest mcp init --client codex npx shadcn-vue@latest mcp init --client cursor npx shadcn-vue@latest mcp init --client vscode

---

Configuration

配置

shadcn-vue uses

components.json

to configure:

Component paths (
```
@/components/ui
```
)
Utils location (
```
@/lib/utils
```
)
Tailwind config paths
TypeScript paths

Full example: See

templates/components.json

or generate via

npx shadcn-vue@latest init

shadcn-vue使用

components.json

进行配置：

组件路径（
```
@/components/ui
```
）
工具库位置（
```
@/lib/utils
```
）
Tailwind配置路径
TypeScript路径

完整示例: 查看

templates/components.json

或通过

npx shadcn-vue@latest init

生成

Utils Library

工具库

The

@/lib/utils.ts

file provides the

cn()

helper for merging Tailwind classes:

Combines multiple className strings
Uses
```
clsx
```
+
```
tailwind-merge
```
for conflict resolution

Auto-generated by

shadcn-vue init

- no manual setup needed.

@/lib/utils.ts

文件提供

cn()

工具函数，用于合并Tailwind类：

合并多个className字符串
使用
```
clsx
```
+
```
tailwind-merge
```
解决冲突

自动生成：由

shadcn-vue init

自动生成，无需手动配置。