111k
新建

shadcn

PreviousNext

使用 shadcn CLI 向项目添加组件。

init

使用 init 命令为新项目初始化配置和依赖。

init 命令会安装依赖、添加 cn 工具函数，并为项目配置 CSS 变量。

pnpm dlx shadcn@latest init

选项

Usage: shadcn init [options] [components...]
 
初始化你的项目并安装依赖
 
Arguments:
  components              组件的名称、URL 或本地路径
 
Options:
  -t, --template <template>  要使用的模板。（next、vite、start、react-router、laravel、astro）
  -b, --base <base>          要使用的组件库。（radix、base）
  -p, --preset [name]        使用预设配置。（名称、URL 或预设代码）
  -n, --name <name>          新项目的名称。
  -d, --defaults             使用默认配置。（默认：false）
  -y, --yes                  跳过确认提示。（默认：true）
  -f, --force                强制覆盖现有配置。（默认：false）
  -c, --cwd <cwd>            工作目录。默认是当前目录。
  -s, --silent               静默输出。（默认：false）
  --monorepo                 生成 monorepo 项目骨架。
  --no-monorepo              跳过 monorepo 提示。
  --reinstall                重新安装已有的 UI 组件。
  --no-reinstall             不重新安装已有的 UI 组件。
  --rtl                      启用 RTL 支持。
  --no-rtl                   禁用 RTL 支持。
  --css-variables            使用 CSS 变量进行主题设置。（默认：true）
  --no-css-variables         不使用 CSS 变量进行主题设置。
  -h, --help                 显示命令帮助

create 命令是 init 的别名：

pnpm dlx shadcn@latest create

add

使用 add 命令向项目添加组件和依赖。

pnpm dlx shadcn@latest add [component]

选项

Usage: shadcn add [options] [components...]
 
向你的项目添加一个组件
 
Arguments:
  components           组件的名称、URL 或本地路径
 
Options:
  -y, --yes            跳过确认提示。（默认：false）
  -o, --overwrite      覆盖已有文件。（默认：false）
  -c, --cwd <cwd>      工作目录。默认是当前目录。
  -a, --all            添加所有可用组件。（默认：false）
  -p, --path <path>    组件要添加到的路径。
  -s, --silent         静默输出。（默认：false）
  --dry-run            在不写入文件的情况下预览更改。（默认：false）
  --diff [path]        显示文件差异。
  --view [path]        显示文件内容。
  -h, --help           显示命令帮助

view

使用 view 命令在安装前查看 registry 中的项目。

pnpm dlx shadcn@latest view [item]

你可以一次查看多个项目：

pnpm dlx shadcn@latest view button card dialog

也可以查看来自命名空间 registry 的项目：

pnpm dlx shadcn@latest view @acme/auth @v0/dashboard

Options

Usage: shadcn view [options] <items...>
 
查看 registry 中的项目
 
Arguments:
  items            要查看的项目名称或 URL
 
Options:
  -c, --cwd <cwd>  工作目录。默认是当前目录。
  -h, --help       显示命令帮助

search

使用 search 命令在 registry 中搜索项目。

pnpm dlx shadcn@latest search [registry]

你可以按查询词搜索：

pnpm dlx shadcn@latest search @shadcn -q "button"

也可以一次搜索多个 registry：

pnpm dlx shadcn@latest search @shadcn @v0 @acme

list 命令是 search 的别名：

pnpm dlx shadcn@latest list @acme

Options

Usage: shadcn search|list [options] <registries...>
 
在多个 registry 中搜索项目
 
Arguments:
  registries             用于搜索项目的 registry 名称或 URL。名称
                         必须以 @ 开头。
 
Options:
  -c, --cwd <cwd>        工作目录。默认是当前目录。
  -q, --query <query>    查询字符串
  -l, --limit <number>   每个 registry 显示的项目最大数量（默认："100"）
  -o, --offset <number>  要跳过的项目数量（默认："0"）
  -h, --help             显示命令帮助

build

使用 build 命令生成 registry JSON 文件。

pnpm dlx shadcn@latest build

该命令会读取 registry.json 文件，并在 public/r 目录中生成 registry JSON 文件。

Options

Usage: shadcn build [options] [registry]
 
为 shadcn registry 构建组件
 
Arguments:
  registry             registry.json 文件路径（默认："./registry.json"）
 
Options:
  -o, --output <path>  JSON 文件输出目录（默认："./public/r")
  -c, --cwd <cwd>      工作目录。默认是当前目录。
  -h, --help           显示命令帮助

如需自定义输出目录，请使用 --output 选项。

pnpm dlx shadcn@latest build --output ./public/registry

docs

使用 docs 命令获取组件的文档和 API 参考。

pnpm dlx shadcn@latest docs [component]

Options

Usage: shadcn docs [options] [component]
 
获取组件的文档和 API 参考
 
Arguments:
  component          要获取文档的组件
 
Options:
  -c, --cwd <cwd>    工作目录。默认是当前目录。
  -b, --base <base>  要使用的 base，可选 'base' 或 'radix'。默认使用项目 base。
  --json             以 JSON 输出。（默认：false）
  -h, --help         显示命令帮助

info

使用 info 命令获取项目信息。

pnpm dlx shadcn@latest info

Options

Usage: shadcn info [options]
 
获取项目信息
 
Options:
  -c, --cwd <cwd>  工作目录。默认是当前目录。
  --json            以 JSON 输出。（默认：false）
  -h, --help        显示命令帮助

migrate

使用 migrate 命令对项目运行迁移。

pnpm dlx shadcn@latest migrate [migration]

Available Migrations

MigrationDescription
icons将你的 UI 组件迁移到其他图标库。
radix迁移到 radix-ui。
rtl迁移你的组件以支持 RTL（从右到左）。

Options

Usage: shadcn migrate [options] [migration] [path]
 
run a migration.
 
Arguments:
  migration        the migration to run.
  path             optional path or glob pattern to migrate.
 
Options:
  -c, --cwd <cwd>  the working directory. defaults to the current directory.
  -l, --list       list all migrations. (default: false)
  -y, --yes        skip confirmation prompt. (default: false)
  -h, --help       display help for command

migrate rtl

rtl 迁移会将你的组件转换为支持 RTL（从右到左）语言。

pnpm dlx shadcn@latest migrate rtl

这会：

  1. 更新 components.json，将 rtl 设为 true
  2. 将物理 CSS 属性转换为逻辑属性等价项（例如 ml-4 → ms-4，text-left → text-start）
  3. 在需要的地方添加 rtl: 变体（例如 space-x-4 → space-x-4 rtl:space-x-reverse）

迁移特定文件

你可以迁移特定文件，也可以使用 glob 模式：

# 迁移单个文件
npx shadcn@latest migrate rtl src/components/ui/button.tsx
 
# 迁移匹配 glob 模式的文件
npx shadcn@latest migrate rtl "src/components/ui/**"

如果未提供路径，迁移会转换你 ui 目录中的所有文件（来自 components.json）。

migrate radix

radix 迁移会将你从单独的 @radix-ui/react-* 包导入，更新为统一的 radix-ui 包导入。

pnpm dlx shadcn@latest migrate radix

这会：

  1. 将 @radix-ui/react-* 的导入转换为 radix-ui
  2. 将 radix-ui 包添加到你的 package.json

迁移前

import * as DialogPrimitive from "@radix-ui/react-dialog"
import * as SelectPrimitive from "@radix-ui/react-select"

迁移后

import { Dialog as DialogPrimitive, Select as SelectPrimitive } from "radix-ui"

迁移特定文件

你可以迁移特定文件，也可以使用 glob 模式：

# 迁移单个文件。
npx shadcn@latest migrate radix src/components/ui/dialog.tsx
 
# 迁移匹配 glob 模式的文件。
npx shadcn@latest migrate radix "src/components/ui/**"

如果未提供路径，迁移会转换你 ui 目录中的所有文件（来自 components.json）。

完成后，你可以从 package.json 中移除任何未使用的 @radix-ui/react-* 包。