开发工具【免费下载链接】remedaA utility library for JavaScript and TypeScript.项目地址https://gitcode.com/gh_mirrors/re/remeda点击查看免费下载本篇以 remeda 仓库内.agents/skills/shadcn/cli.md为骨架完整梳理 shadcn CLI 的每个命令、全部 flag 及默认值、模板与预设机制并对照仓库中 remeda 官方文档站packages/docsAstro shadcn/ui 构建的真实配置给出可直接落地的实战命令与底层原理。读完你将掌握如何用init/create初始化或创建项目、用add加组件含--dry-run/--diff/--view预览机制、用apply切换主题预设、用info读取项目上下文以及如何在 overwrite / merge / skip 三种策略之间做出正确选择。1. 配置来源与命令运行前提1.1 配置从components.json读取shadcn CLI 的一切配置都来源于项目根目录的components.json文件。该文件声明了样式、别名、图标库、Tailwind 路径等信息CLI 在执行add、apply、info等命令时会自动读取并据此解析目标路径。remeda 仓库中 packages/docs/components.json 就是一个真实示例{ $schema: https://ui.shadcn.com/schema.json, style: new-york, rsc: false, tsx: true, tailwind: { config: , css: src/styles/global.css, baseColor: slate, cssVariables: true, prefix: }, aliases: { components: /components, utils: /lib/utils, ui: /components/ui, lib: /lib, hooks: /hooks }, iconLibrary: lucide }可以看到文档站的别名体系为/components、/components/ui、/lib/utils图标库为lucide全局 CSS 文件是src/styles/global.css。这些字段与下文的info命令输出一一对应是理解后续所有命令行为的前提。1.2 两条铁律原文档对命令执行方式给出了两条强制约束任何使用者都应遵守始终使用项目自身的包管理器运行命令根据项目上下文的packageManager字段选择npx shadcnlatest、pnpm dlx shadcnlatest或bunx --bun shadcnlatest。下文示例统一使用npx shadcnlatest请在实际项目中替换为正确的 runner。remeda 文档站的devDependencies中直接依赖了shadcn: ^4.19.0见 packages/docs/package.json因此在文档站目录内可以直接运行本地 shadcn 命令。只使用下文列出的 flag禁止自行发明或猜测文档没有列出的 flag 就不存在。特别地CLI 会从项目的 lockfile 自动检测包管理器不存在--package-manager这个 flag。2. 命令详解CLI 提供的命令包括init、apply、adddry-run / smart merge、search、view、docs、info、build。下面逐一展开。2.1init— 初始化或创建项目npx shadcnlatest init [components...] [options]在既有项目中初始化 shadcn/ui或在提供--name时创建全新项目并可选择在同一命令中安装组件。FlagShort说明默认值--template template-t模板next, start, vite, next-monorepo, react-router—--preset [name]-p预设配置named、code 或 URL 三种形式—--yes-y跳过确认提示true--defaults-d使用默认配置等价于--templatenext --presetbase-novafalse--force-f强制覆盖已有配置false--cwd cwd-c工作目录当前目录--name name-n新项目名称—--silent-s静默输出false--rtl启用 RTL 支持—--reinstall重新安装已有 UI 组件false--monorepo脚手架化一个 monorepo 项目—--no-monorepo跳过 monorepo 交互提示—注意npx shadcnlatest create是npx shadcnlatest init的别名。快速创建新项目示例源自 SKILL.md 的 Quick Reference# 创建新项目。 npx shadcnlatest init --name my-app --preset base-nova npx shadcnlatest init --name my-app --preset a2r6bw --template vite # 创建 monorepo 项目。 npx shadcnlatest init --name my-app --preset base-nova --monorepo npx shadcnlatest init --name my-app --preset base-nova --template next --monorepo # 初始化既有项目。 npx shadcnlatest init --preset base-nova npx shadcnlatest init --defaults # 快捷方式--templatenext --presetnovabase 样式隐含2.2apply— 将预设应用到既有项目npx shadcnlatest apply [preset] [options]将预设应用到既有项目覆盖预设驱动的配置、字体、CSS 变量以及检测到的 UI 组件。FlagShort说明默认值--preset preset—预设配置named、code 或 URL—--yes-y跳过确认提示false--cwd cwd-c工作目录当前目录--silent-s静默输出false要点位置参数[preset]是--preset preset的简写两者同时提供时必须一致。若未提供预设CLI 会主动邀请打开ui.shadcn.com/create上的自定义预设构建器。apply只适用于已存在components.json的既有项目命令必须在用户项目目录内执行。CLI 会自动保留components.json中当前的 basebase还是radix如果必须在临时/草稿目录中执行例如做--dry-run对比需要显式传--base current-base—— 因为preset code 本身不编码 base。2.3add— 添加组件重要要对比本地组件与上游差异、或预览改动始终使用npx shadcnlatest add component --dry-run、--diff或--view。绝不手动从 GitHub 等来源拉取原始文件——CLI 会自动处理 registry 解析、文件路径与 CSS diff。npx shadcnlatest add [components...] [options]接受组件名、带 registry 前缀的名称如magicui/shimmer-button、URL 或本地路径。FlagShort说明默认值--yes-y跳过确认提示false--overwrite-o覆盖已有文件false--cwd cwd-c工作目录当前目录--all-a添加所有可用组件false--path path-p组件的目标路径—--silent-s静默输出false--dry-run预览所有改动但不写文件false--diff [path]显示差异。不带路径显示前 5 个文件带路径只显示该文件隐含--dry-run—--view [path]显示文件内容。不带路径显示前 5 个文件带路径只显示该文件隐含--dry-run—实际用法# 添加组件。 npx shadcnlatest add button card dialog npx shadcnlatest add magicui/shimmer-button npx shadcnlatest add --allDry-Run 模式--dry-run用于在不写任何文件的情况下预览add将要执行的操作--diff与--view都隐含--dry-run。# 预览全部改动。 npx shadcnlatest add button --dry-run # 显示所有文件的差异前 5 个。 npx shadcnlatest add button --diff # 显示某个具体文件的差异。 npx shadcnlatest add button --diff button.tsx # 显示所有文件的内容前 5 个。 npx shadcnlatest add button --view # 显示某个具体文件的完整内容。 npx shadcnlatest add button --view button.tsx # URL 同样适用。 npx shadcnlatest add https://api.npoint.io/abc123 --dry-run # CSS 差异。 npx shadcnlatest add button --diff globals.css何时使用 dry-run用户问这个操作会添加哪些文件 / 会改动什么→ 用--dry-run覆盖已有组件之前 → 先用--diff预览改动用户想查看组件源码但暂不安装 → 用--view想确认globals.css会有哪些 CSS 改动 → 用--diff globals.css安装第三方 registry 代码前想先审查/审计 → 用--view检查源码。add --dry-run与view的区别当用户要预览对项目的改动时优先用npx shadcnlatest add --dry-run/--diff/--view它展示的是真实会发生的事件解析后的文件路径、与现有文件的 diff、CSS 更新。而npx shadcnlatest view只显示 registry 的原始元数据仅在用户想脱离项目上下文浏览 registry 信息时使用。Smart Merge from Upstream更新已有组件时若需在保留本地改动的前提下合并上游更新采用智能合并工作流先add --dry-run列出所有受影响文件再对每个文件执行add --diff file逐文件决策无本地改动可安全覆盖有本地改动则读取本地文件、分析 diff、在保留本地修改的前提下应用上游更新。完整流程见 SKILL.md 的 Updating Components 一节。绝不未经用户明确批准就使用--overwrite。2.4search— 搜索 registrynpx shadcnlatest search registries... [options]跨 registry 模糊搜索别名为npx shadcnlatest list。不带-q时列出全部条目。FlagShort说明默认值--query query-q搜索关键词—--limit number-l每个 registry 最多返回条数100--offset number-o跳过的条数0--cwd cwd-c工作目录当前目录示例npx shadcnlatest search shadcn -q sidebar npx shadcnlatest search tailark -q statsremeda 文档站的组件选择原则也与此呼应先搜索 registry 中是否已有组件再决定是否手写自定义 UI详见 SKILL.md。2.5view— 查看条目详情npx shadcnlatest view items... [options]显示条目信息含文件内容。示例npx shadcnlatest view shadcn/button。2.6docs— 获取组件文档 URLnpx shadcnlatest docs components... [options]输出组件文档、示例与 API 参考的已解析 URL接受一个或多个组件名。拿到 URL 后需自行抓取内容。npx shadcnlatest docs input button的示例输出base radix input docs https://ui.shadcn.com/docs/components/radix/input examples https://raw.githubusercontent.com/.../examples/input-example.tsx button docs https://ui.shadcn.com/docs/components/radix/button examples https://raw.githubusercontent.com/.../examples/button-example.tsx部分组件还包含指向底层库的api链接例如 command 组件对应cmdk。SKILL.md 强调创建、修复、调试或使用组件时务必先运行docs并抓取 URL确保基于正确的 API 与用法模式而不是猜测。2.7diff— 检查更新勿用不要使用这个命令请改用npx shadcnlatest add --diff。2.8info— 项目信息npx shadcnlatest info [options]显示项目信息与components.json配置。建议最先运行此命令以发现项目的框架、别名、Tailwind 版本与解析路径。FlagShort说明默认值--cwd cwd-c工作目录当前目录Project Info 字段字段类型含义frameworkstring检测到的框架next、vite、react-router、start等frameworkVersionstring框架版本如15.2.4isSrcDirboolean是否使用src/目录isRSCboolean是否启用 React Server ComponentsisTsxboolean是否使用 TypeScripttailwindVersionstringv3或v4tailwindConfigFilestringTailwind 配置文件路径tailwindCssFilestring全局 CSS 文件路径aliasPrefixstring导入别名前缀如、~、/packageManagerstring检测到的包管理器npm、pnpm、yarn、bunremeda 文档站的场景下framework为astro、tailwindVersion为v4依赖tailwindcss/vite与tailwindcss^4.3.3见 packages/docs/package.jsontailwindCssFile为src/styles/global.cssaliasPrefix为。Components.json 字段字段类型含义basestring原语库radix或base——决定组件 API 与可用 propsstylestring视觉风格如nova、vegarscboolean配置中的 RSC 标志tsxbooleanTypeScript 标志tailwind.configstringTailwind 配置路径tailwind.cssstring全局 CSS 路径——自定义 CSS 变量就写在这里iconLibrarystring图标库——决定图标导入包如lucide-react、tabler/icons-reactaliases.componentsstring组件导入别名如/componentsaliases.utilsstringutils 导入别名如/lib/utilsaliases.uistringUI 组件别名如/components/uialiases.libstringlib 别名如/libaliases.hooksstringhooks 别名如/hooksresolvedPathsobject每个别名对应的绝对文件系统路径registriesobject配置的自定义 registriesLinks 字段info输出还包含一个Links区段提供组件文档、源码和示例的模板化 URL要获取已解析的 URL改用npx shadcnlatest docs component。remeda 文档站对这些字段的实际运用可以直接对照 packages/docs/components.jsoniconLibrary: lucide对应依赖中的lucide-reactaliases.ui对应src/components/ui/目录badge.tsx、button.tsx、card.tsx、dropdown-menu.tsx、scroll-area.tsx、sheet.tsx等 shadcn 组件均位于该目录aliases.utils则对应 packages/docs/src/lib/utils.ts 中的cn()函数import { clsx, type ClassValue } from clsx; import { twMerge } from tailwind-merge; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }cn()正是 shadcn 组件中用于条件类名合并的标准工具对应 styling 规则 中使用cn()做条件类的强制要求。2.9build— 构建自定义 registrynpx shadcnlatest build [registry] [options]将registry.json构建为单个 JSON 文件以用于分发。默认输入./registry.json默认输出./public/r。FlagShort说明默认值--output path-o输出目录./public/r--cwd cwd-c工作目录当前目录3. Templates 模板值框架Monorepo 支持nextNext.js支持viteVite支持startTanStack Start支持react-routerReact Router支持astroAstro支持laravelLaravel不支持所有模板都支持通过--monorepoflag 进行 monorepo 脚手架传入时CLI 使用 monorepo 专用模板目录如next-monorepo、vite-monorepo。当--monorepo与--no-monorepo都未传入时CLI 会交互式询问。Laravel 不支持 monorepo 脚手架。值得说明的是remeda 文档站本身就是 Astro 项目packages/docs的构建脚本为astro build这对应模板表中的astro模板而文档站的 shadcn 组件button.tsx、card.tsx等以.tsx形式被.astro页面引用体现了 Astro shadcn/ui 的组合模式。4. Presets 预设通过--preset指定预设共有三种形式Named命名--preset nova或--preset lyraCode代码--preset a2r6bw版本前缀的 base62 字符串如a2r6bw或b0URL--preset https://ui.shadcn.com/init?baseradixstylenova...已知命名预设nova、vega、maia、lyra、mira、luma。重要绝不手动解码、抓取或解析 preset code。Preset code 是不透明的直接传给npx shadcnlatest init --preset code让 CLI 自行解析即可。覆盖既有项目的预设时使用npx shadcnlatest apply --preset code。5. Switching Presets 切换预设切换预设前必须询问用户对已有组件执行overwrite覆盖/ merge合并/ skip跳过哪种策略Overwrite / Re-install覆盖 / 重装→npx shadcnlatest apply --preset code。以新预设样式覆盖所有检测到的组件文件。适用于用户尚未自定义组件的情况。Merge合并→ 先npx shadcnlatest init --preset code --force --no-reinstall再运行npx shadcnlatest info获取已安装组件列表然后逐一使用 smart merge 工作流 更新以保留本地改动。适用于用户已自定义组件的情况。Skip跳过→npx shadcnlatest init --preset code --force --no-reinstall。只更新配置与 CSS 变量已有组件保持原样。实际命令# 将预设应用到既有项目。 npx shadcnlatest apply --preset a2r6bw npx shadcnlatest apply a2r6bw # 仅更新部分预设theme/font可逗号组合icon 有意不支持。 npx shadcnlatest apply --preset a2r6bw --only theme npx shadcnlatest apply --preset a2r6bw --only font npx shadcnlatest apply --preset a2r6bw --only theme,font # 保留已有组件的切换skip 策略。 npx shadcnlatest init --preset nova --force --no-reinstall三条硬性前提预设命令始终在用户项目目录内执行apply只对存在components.json的既有项目生效CLI 自动保留components.json中的当前 basebasevsradix若必须在临时目录操作如--dry-run对比需显式传--base current-base因为 preset code 不编码 base。SKILL.md 还补充了一个partial策略npx shadcnlatest apply --preset code --only theme,font只更新选中部分而不重装 UI 组件。icon刻意不支持--only因为图标变更可能要求完整重装组件并做转换见 SKILL.md 第 9 步工作流。6. 主题定制与 CSS 变量配套能力切换预设之外直接编辑 CSS 变量也能改主题。remeda 文档站的 packages/docs/src/styles/global.css 就是 shadcn 主题 CSS 变量的完整落地实例其中:root浅色部分示例:root { --background: oklch(1 0 0); --foreground: oklch(0.129 0.042 264.695); --card: oklch(1 0 0); --primary: oklch(0.546 0.2153 262.87); --muted: oklch(0.968 0.007 247.896); --destructive: oklch(0.577 0.245 27.325); --border: oklch(0.929 0.013 255.508); --input: oklch(0.929 0.013 255.508); --ring: oklch(0.869 0.022 252.894); --chart-1: oklch(0.646 0.222 41.116); --radius: 0.625rem; --sidebar: oklch(0.984 0.003 247.858); }这印证了 CLI 文档中的关键机制颜色使用 OKLCH 格式oklch(亮度 色度 色相)采用name/name-foreground约定base 变量用于背景-foreground用于该背景上的文字/图标--radius全局控制圆角组件据此派生rounded-lgvar(--radius)、rounded-mdcalc(var(--radius) - 2px)。组件通过 Tailwind 语义工具类bg-primary、text-muted-foreground引用这些变量——修改变量即可全局改变所有引用它的组件。完整变量表与深浅色切换、Tailwind v3/v4 注册自定义颜色的方法见 customization.md。7. 关联参考资源本 CLI 文档是.agents/skills/shadcn/技能包的一部分配套资料可进一步深化使用SKILL.md — 组件使用原则、关键模式、组件选择表、完整工作流含 smart merge 更新流程rules/styling.md — 语义色、variant、className、间距、size、truncate、暗色模式、cn()、z-index 的正确/错误写法rules/forms.md — FieldGroup/Field/InputGroup/ToggleGroup/FieldSet 与校验态rules/composition.md — Groups、overlays、Card、Tabs、Avatar、Alert、Empty、Toast、Separator、Skeleton、Badge、Button 加载态rules/icons.md —data-icon、图标尺寸、图标以对象而非字符串传递rules/base-vs-radix.md —asChildvsrender、Select/ToggleGroup/Slider/Accordion 两套 API 差异customization.md — 主题、CSS 变量、扩展组件mcp.md — CLI 内置的 MCP 服务器shadcn mcp/shadcn mcp init支持 AI 助手搜索、浏览、查看与安装组件。这些文件与本文档共同构成一套完整的 shadcn/ui 工程化指南本文档负责命令与参数SKILL.md 负责使用原则与工作流rules 目录负责代码写法规范。remeda 文档站的 packages/docs/components.json 与 packages/docs/src/styles/global.css 则是这套体系在真实项目中的落地样本可作为理解配置与输出之间对应关系的第一手参照。赞分享开发工具【免费下载链接】remedaA utility library for JavaScript and TypeScript.项目地址https://gitcode.com/gh_mirrors/re/remeda点击查看免费下载相关推荐new-api 前端开发实战shadcn/ui CLI 完整命令参考init / apply / add / dry-run / 预设切换new api 前端开发实战shadcn/ui CLI 完整命令参考init / apply / add / dry run / 预设切换 本篇基于 ne后端API网关LLM 网关大模型认证鉴权桌面应用shadcn-vue CLI 完全指南init、add、apply、view、search、build 与 migrate 全命令实战shadcn vue CLI 完全指南init、add、apply、view、search、build 与 migrate 全命令实战 本文以 CLI 文档UI组件前端shadcn-vue CLI 完整命令参考init、apply、add 与预设系统的实战指南shadcn vue CLI 完整命令参考init、apply、add 与预设系统的实战指南 本篇技术指南以 skills/shadcn vue/cli.mdUI组件前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考