new-api 前端 shadcn/ui CLI 实战指南从 components.json 到 init/apply/add 的完整命令参考【免费下载链接】new-apiAI模型聚合管理中转分发系统一个应用管理您的所有AI模型支持将多种大模型转为统一格式调用支持OpenAI、Claude、Gemini等格式可供个人或者企业内部管理与分发渠道使用。 A Unified AI Model Management Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api本文基于 new-api 仓库中 vendored 的 shadcn CLI 参考文档.agents/skills/shadcn-ui/vendor/shadcn/cli.md展开面向在web/前端目录中操作 shadcn/ui 的开发者与 AI Agent。读完后你将掌握 shadcn CLI 的全部命令init、apply、add、search、view、docs、info、build、dry-run/diff 预览机制、Preset预设三种指定方式与切换策略并能结合 new-api 真实的web/components.json配置与shadcn依赖版本验证每个命令在本仓库中的实际行为。一、文档定位new-api 里的 shadcn 技能与运行环境new-api 是一个 AI 模型聚合管理中转分发系统其管理控制台前端位于web/目录rsbuild React 19 Tailwind CSS v4。仓库在 .agents/skills/shadcn-ui/SKILL.md 中内置了一个项目感知的 shadcn/ui 技能它告诉 AI 助手如何在本仓库中发现、安装、组合和定制 shadcn 组件技能引用的上游文档快照被 vendored 在 .agents/skills/shadcn-ui/vendor/shadcn/ 目录下本文的核心参考 cli.md 即来自该目录上游来源记录见 UPSTREAM.txt。理解命令前先明确 new-api 的实际运行环境前端工程根目录是web/components.json位于 web/components.jsonpackage.json位于 web/package.json。shadcn已作为 devDependency 引入web/package.json中声明了shadcn: ^4.12.0锁文件为web/bun.lock项目包管理器是Bun。正确的调用方式SKILL.md 给出的标准入口是cd web bunx shadcnlatest info --json已安装组件web/src/components/ui/下已有 60 个组件文件button.tsx、dialog.tsx、select.tsx、sidebar.tsx、form.tsx、sonner.tsx等执行add前应先用info或目录列表确认组件是否已存在。二、CLI 总则包管理器、包执行器与只信文档里的 flagcli.md 开篇给出两条强约束它们直接决定在 new-api 中如何敲命令始终用项目对应的包执行器调用npx shadcnlatest、pnpm dlx shadcnlatest或bunx --bun shadcnlatest具体选择取决于项目的packageManager。new-api 的web/使用 Bun存在bun.lock因此应优先用bunx --bun shadcnlatest本文示例沿用原文档的npx shadcnlatest写法实际执行时请替换为对应执行器。只使用文档中列出的 flag文档明确警告不要发明或猜测 flag未列出的 flag 不存在。例如CLI 会根据项目锁文件自动检测包管理器不存在--package-managerflag——这对 new-api 意味着在web/目录下运行CLI 自动识别为 bun无需也不能额外指定。所有配置都从components.json读取这就是为什么info命令被要求先跑它。三、init初始化现有项目或创建新项目npx shadcnlatest init [components...] [options]init可以在现有项目中初始化 shadcn/ui也可以在提供--name时直接创建新项目还支持在同一步中安装组件。npx shadcnlatest create是init的别名。完整 flag 参考Flag短写说明默认值--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 提示—在 new-api 场景中init的典型用途有两类一是在全新前端工程里初始化并一步装齐组件init button card二是在 Preset 切换的merge/skip流程中配合--force --no-reinstall只更新配置与 CSS 变量见第八节。四、apply把 Preset 应用到已有项目npx shadcnlatest apply [preset] [options]apply将预设应用到已有项目会覆盖预设驱动的配置、字体、CSS 变量以及被检测到的 UI 组件。Flag短写说明默认值--preset preset—预设配置named、code 或 URL—--yes-y跳过确认提示false--cwd cwd-c工作目录当前目录--silent-s静默输出false要点[preset]位置参数等价于--preset preset两者同时提供时必须一致。未提供 preset 时CLI 会引导打开ui.shadcn.com/create的自定义预设构建器。apply只能在存在components.json的已有项目中工作——对 new-api 来说就是web/目录。五、add安装组件以及 dry-run / diff / view 预览体系add是日常使用频率最高的命令。文档对此有一条加粗的重要约束要对比本地组件与上游、或预览变更时永远使用add component --dry-run、--diff或--view。绝不要手工从 GitHub 或其他来源拉取原始文件。CLI 会自动处理 registry 解析、文件路径与 CSS diff。npx shadcnlatest add [components...] [options]add的参数接受组件名、registry 前缀名如magicui/shimmer-buttonnew-api 的web/components.json中就配置了ai-elementsregistry可按ai-elements/name引用、URL 或本地路径。Flag短写说明默认值--yes-y跳过确认提示false--overwrite-o覆盖已有文件false--cwd cwd-c工作目录当前目录--all-a添加所有可用组件false--path path-p组件目标路径—--silent-s静默输出false--dry-run—预览所有变更但不写文件false--diff [path]—显示 diff。不带 path 显示前 5 个文件带 path 只显示该文件隐含--dry-run—--view [path]—显示文件内容。不带 path 显示前 5 个文件带 path 只显示该文件隐含--dry-run—5.1 Dry-Run 模式完整示例--dry-run用于在不写任何文件的情况下预览add将做什么--diff与--view都隐含--dry-run# 预览所有变更 npx shadcnlatest add button --dry-run # 显示所有文件的 diff最多前 5 个 npx shadcnlatest add button --diff # 显示指定文件的 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 diff npx shadcnlatest add button --diff globals.css在 new-api 中注意全局 CSS 不是globals.cssweb/components.json声明的是tailwind: { css: src/styles/index.css }因此检查 CSS 变更时应写--diff src/styles/index.css对应 web/src/styles/index.css。何时使用 dry-run原文档列举的场景用户问这会添加哪些文件 / 会改什么 → 用--dry-run覆盖已有组件之前 → 先用--diff预览变更想在不安装的情况下检查组件源码 → 用--view检查对全局 CSSnew-api 中为src/styles/index.css会有什么改动 → 用--diff css 文件用户要求在安装前审查第三方 registry 代码 → 用--view查看源码。5.2add --dry-run与view的分工原文档明确给出了二者取舍当用户想预览对其项目的变更时优先add --dry-run/--diff/--view——它展示的是用户项目里将发生的精确结果解析后的文件路径、与现有文件的 diff、CSS 更新。而view只显示 registry 的原始元数据只在用户想脱离项目上下文浏览 registry 信息时使用。5.3 Smart Merge更新组件时保留本地修改cli.md 将从上游智能合并Smart Merge的完整流程指向 official-shadcn-ui-workflow.md 的 Updating Components 一节该流程在本仓库可确认为四步npx shadcnlatest add component --dry-run查看所有受影响文件对每个文件执行npx shadcnlatest add component --diff file对比上游与本地的差异按 diff 逐文件决策无本地修改 → 可直接覆盖有本地修改 → 读取本地文件分析 diff在上游更新基础上保留本地改动用户明确说全部更新 → 用--overwrite但需先确认未经用户明确批准永远不使用--overwrite。这套流程正是 new-api 这类已深度定制过组件的项目web/src/components/ui/下大量组件都有本地业务修改更新 shadcn 组件时的标准路径。六、search、view、docs组件发现与文档检索6.1search— 模糊搜索 registrynpx shadcnlatest search registries... [options]也别名npx shadcnlatest list。不带-q时列出 registry 全部条目。Flag短写说明默认值--query query-q搜索关键词—--limit number-l每个 registry 最多条目数100--offset number-o跳过的条目数0--cwd cwd-c工作目录当前目录结合 new-api 的web/components.json配置了ai-elementsregistry可以搜索官方 registry 与ai-elements两个来源例如npx shadcnlatest search shadcn ai-elements -q sidebar。6.2view— 查看 registry 条目详情npx shadcnlatest view items...显示条目信息含文件内容例如npx shadcnlatest view shadcn/button。用于浏览尚未安装的 registry 条目。6.3docs— 获取组件文档 URLnpx shadcnlatest docs components...输出组件文档、示例、API 参考的解析后 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——new-api 的web/package.json中确实依赖了cmdk。vendored 的工作流文档official-shadcn-ui-workflow.md进一步要求创建、修复或调试组件前总是先跑docs并抓取 URL以保证用的是正确的 API 而不是猜测。6.4diff顶级命令— 已不推荐cli.md 对顶级diff命令的说明只有一句话不要使用它请改用npx shadcnlatest add --diff。七、info项目上下文与components.json字段全解npx shadcnlatest info [options]显示项目信息与components.json配置。文档建议先跑它以此发现项目的框架、别名、Tailwind 版本与解析后的路径。唯一 flag 是--cwd cwd/-c默认当前目录。7.1 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、bun对 new-api 而言packageManager应报告为bun依据web/bun.locktailwindVersion为v4依据web/package.json中tailwindcss: ^4.3.2isSrcDir与isTsx均为 true组件位于web/src/。7.2 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已配置的自定义 registryinfo输出还包括一个Links部分包含组件文档、源码、示例的模板化 URL需要解析后的具体 URL 时请改用npx shadcnlatest docs component。7.3build构建自定义 registrynpx shadcnlatest build [registry] [options]将registry.json构建为可分发的独立 JSON 文件。默认输入./registry.json默认输出./public/r。Flag短写说明默认值--output path-o输出目录./public/r--cwd cwd-c工作目录当前目录这是从消费 registry 到发布 registry的能力如果团队要把内部组件沉淀为 registry 供其他项目add用build生成产物即可。八、Templates 与 Presets模板矩阵和三种预设指定方式8.1 模板矩阵值框架Monorepo 支持nextNext.js是viteVite是startTanStack Start是react-routerReact Router是astroAstro是laravelLaravel否所有模板都支持通过--monorepo做 monorepo 脚手架传入该 flag 时 CLI 使用 monorepo 专用模板目录如next-monorepo、vite-monorepo。当--monorepo与--no-monorepo都未传时CLI 会交互询问。Laravel 不支持 monorepo 脚手架。8.2 Preset 的三种指定方式--preset接受三种形式命名预设--preset nova或--preset lyra编码预设--preset a2r6bw带版本前缀的 base62 字符串如a2r6bw或b0URL 预设--preset https://ui.shadcn.com/init?baseradixstylenova...。两条强约束值得单独强调永远不要手工解码、抓取或解析 preset code。Preset code 是不透明opaque的直接传给npx shadcnlatest init --preset code让 CLI 处理解析覆盖已有项目的预设则用npx shadcnlatest apply --preset code。工作流文档中还提供了辅助检查命令preset resolve查看当前项目已解析的 preset支持--json、preset decode code、preset url code、preset open code——用于在切换前只读地检查当前/目标预设状态。九、切换 Presetoverwrite / merge / skip 三选一原文档要求先询问用户现有组件是 overwrite、merge 还是 skip三种策略对应命令如下策略命令适用场景Overwrite / Re-installnpx shadcnlatest apply --preset code用户没有自定义过组件时用新预设风格覆盖所有检测到的组件文件Mergenpx shadcnlatest init --preset code --force --no-reinstall然后npx shadcnlatest info获取已装组件列表逐个用 Smart Merge 工作流更新用户已自定义组件需保留本地修改Skipnpx shadcnlatest init --preset code --force --no-reinstall只更新配置与 CSS 变量组件原样保留原文档 Merge 与 Skip 的入口命令相同区别在于 Merge 之后还要逐组件执行 smart merge完整 merge 流程见 official-shadcn-ui-workflow.md 的 Workflow 第 9 步。执行约束预设命令必须在用户项目目录内运行new-api 即web/apply仅在有components.json的已有项目中生效。CLI 会自动从components.json保留当前的 basebasevsradix。如果必须在临时/scratch 目录中运行如做--dry-run对比要显式传--base current-base——preset code 不编码 base 信息。十、对照 new-api 真实配置字段落地与实操核对结合 web/components.json 的实际内容可以逐字段验证上面info字段表的语义{ $schema: https://ui.shadcn.com/schema.json, style: base-nova, rsc: false, tsx: true, tailwind: { config: , css: src/styles/index.css, baseColor: neutral, cssVariables: true, prefix: }, iconLibrary: hugeicons, aliases: { components: /components, utils: /lib/utils, ui: /components/ui, lib: /lib, hooks: /hooks }, menuColor: inverted, menuAccent: subtle, registries: { ai-elements: https://registry.ai-sdk.dev/{name}.json } }由此可以确认 new-api 前端的 shadcn 上下文风格base-novabase 基础库 nova 视觉风格rsc: false说明是纯客户端渲染与tsx: true一起决定了info会报告isRSCfalse、isTsxtrueTailwindconfig为空 css指向src/styles/index.css是典型的 Tailwind v4 CSS-first 配置与web/package.json中tailwindcss: ^4.3.2及rsbuild/plugin-tailwindcss插件相印证cssVariables: true意味着主题变量走 CSS 变量图标库hugeiconsweb/package.json依赖了hugeicons/react与hugeicons/core-free-icons。vendored 工作流文档明确要求添加第三方 registry 组件后若其图标导入与项目iconLibrary不一致如 registry 用lucide-react必须替换为本项目图标库——new-api 正属于这种情况别名/components/ui与web/src/components/ui/目录一一对应即上文列出的 60 组件文件自定义 registryai-elements指向https://registry.ai-sdk.dev/{name}.json因此add支持ai-elements/组件名这类 registry 前缀写法额外配置项menuColor: inverted与menuAccent: subtle是 preset 驱动的菜单样式选项切换 preset 时由apply/init一并处理。配套的仓库内实践规则web/AGENTS.md也规定了开发前必须先读取shadcn-ui技能、用rg检索src/components/与相关src/features/、阅读候选组件实现与调用示例后再动手——这与infosearchdocs的命令体系是同一套先探测项目上下文再写代码的方法论。十一、快速参考Quick Reference综合 cli.md 与工作流文档最常用的命令序列如下# 在 new-api 前端中包管理器为 Bun cd web bunx shadcnlatest info # 第一步永远是它 # 创建新项目 npx shadcnlatest init --name my-app --preset base-nova npx shadcnlatest init --name my-app --preset a2r6bw --template vite npx shadcnlatest init --name my-app --preset base-nova --monorepo # 为已有项目应用预设 npx shadcnlatest apply a2r6bw # 检查预设状态 npx shadcnlatest preset resolve --json npx shadcnlatest preset decode a2r6bw # 添加组件 npx shadcnlatest add button card dialog npx shadcnlatest add magicui/shimmer-button # 安装/更新前预览本仓库推荐的更新姿势 npx shadcnlatest add button --dry-run npx shadcnlatest add button --diff button.tsx npx shadcnlatest add acme/form --view button.tsx # 搜索与文档 npx shadcnlatest search shadcn ai-elements -q sidebar npx shadcnlatest docs button dialog select npx shadcnlatest view shadcn/button小结这篇 cli.md 参考文档以components.json为单一配置源把 shadcn CLI 收敛为一条清晰的工作流info探测上下文 →search/docs/view发现与核实组件 →add配合--dry-run/--diff/--view安全安装或 smart merge 更新 →apply/init管理 preset 切换overwrite/merge/skip 三选一。在 new-api 仓库中这套命令以cd web bunx shadcnlatest ...的形式运行配合 web/components.json 中base-nova风格、hugeicons 图标库与ai-elements自定义 registry 的配置即可在保留web/src/components/ui/本地定制的前提下稳定地增删、预览和更新 shadcn 组件。【免费下载链接】new-apiAI模型聚合管理中转分发系统一个应用管理您的所有AI模型支持将多种大模型转为统一格式调用支持OpenAI、Claude、Gemini等格式可供个人或者企业内部管理与分发渠道使用。 A Unified AI Model Management Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考