components.json

项目配置文件。

components.json 保存了项目所需的配置。

CLI 会根据这个文件了解你的项目结构，从而生成与之匹配的组件。

注意：`components.json` 并非必需

只有在使用 CLI 添加组件时才需要该文件。 如果你采用复制粘贴的方式，就不必创建它。

运行以下命令即可在项目中生成 components.json：


pnpm dlx shadcn@latest init

详见 CLI 章节。

$schema

components.json 的 JSON Schema 可在这里查看。

components.json

{
  "$schema": "https://ui.shadcn.com/schema.json"
}

style

组件所使用的样式主题。初始化后不可修改。

components.json

{
  "style": "new-york"
}

default 样式已废弃，请改用 new-york。

tailwind

Tailwind 配置，帮助 CLI 识别项目中的 Tailwind 设置。Tailwind 的安装步骤请参考安装章节。

tailwind.config

tailwind.config.js 所在路径。如果使用 Tailwind CSS v4，请留空。

components.json

{
  "tailwind": {
    "config": "tailwind.config.js" | "tailwind.config.ts"
  }
}

tailwind.css

导入 Tailwind 的 CSS 文件路径。

components.json

{
  "tailwind": {
    "css": "styles/global.css"
  }
}

tailwind.baseColor

用于生成默认配色。初始化后不可修改。

components.json

{
  "tailwind": {
    "baseColor": "gray" | "neutral" | "slate" | "stone" | "zinc"
  }
}

tailwind.cssVariables

可在 CSS 变量与 Tailwind 工具类之间选择主题方案。

使用工具类：将 tailwind.cssVariables 设为 false
使用 CSS 变量：将其设为 true

components.json

{
  "tailwind": {
    "cssVariables": `true` | `false`
  }
}

详情参见主题文档。

该选项初始化后不可修改。 若需切换主题方案，需要删除并重新安装组件。

tailwind.prefix

Tailwind 工具类前缀。组件会带着此前缀生成。

components.json

{
  "tailwind": {
    "prefix": "tw-"
  }
}

rsc

是否启用 React Server Components 支持。若设为 true，CLI 会自动为客户端组件添加 use client 指令。

components.json

{
  "rsc": `true` | `false`
}

tsx

选择生成 TypeScript 或 JavaScript 组件。设为 false 时将生成 .jsx 组件。

components.json

{
  "tsx": `true` | `false`
}

aliases

CLI 会配合 tsconfig.json 或 jsconfig.json 中的 paths 配置，将生成的组件放在正确的路径下。

请务必在 tsconfig.json/jsconfig.json 中设置好这些别名。

重要： 如果使用 src 目录，请确保它已包含在 paths 配置中。

aliases.utils

工具函数的导入别名。

components.json

{
  "aliases": {
    "utils": "@/lib/utils"
  }
}

aliases.components

组件目录的导入别名。

components.json

{
  "aliases": {
    "components": "@/components"
  }
}

aliases.ui

ui 组件的导入别名。CLI 会根据 aliases.ui 决定 ui 组件的安装位置，可借此自定义目录结构。

components.json

{
  "aliases": {
    "ui": "@/app/ui"
  }
}

aliases.lib

lib 下函数（如 format-date、generate-id）的导入别名。

components.json

{
  "aliases": {
    "lib": "@/lib"
  }
}

aliases.hooks

hooks（如 use-media-query、use-toast）的导入别名。

components.json

{
  "aliases": {
    "hooks": "@/hooks"
  }
}

registries

配置多个资源注册表，支持从公共或私有源安装组件、库、工具等。

详见命名空间注册表文档。

基础配置

使用 URL 模板定义注册表：

components.json

{
  "registries": {
    "@v0": "https://v0.dev/chat/b/{name}",
    "@acme": "https://registry.acme.com/{name}.json",
    "@internal": "https://internal.company.com/{name}.json"
  }
}

安装时 {name} 会被替换为资源名称。

带鉴权的高级配置

私有注册表通常需要鉴权：

components.json

{
  "registries": {
    "@private": {
      "url": "https://api.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}",
        "X-API-Key": "${API_KEY}"
      },
      "params": {
        "version": "latest"
      }
    }
  }
}

${VAR_NAME} 形式的环境变量会自动从系统环境中展开。

使用命名空间注册表

配置完成后，即可使用命名空间语法安装资源：

# 安装注册表中的资源
npx shadcn@latest add @v0/dashboard
 
# 安装私有注册表资源
npx shadcn@latest add @private/button
 
# 一次安装多个资源
npx shadcn@latest add @acme/header @internal/auth-utils

示例：多注册表配置

components.json

{
  "registries": {
    "@shadcn": "https://ui.shadcn.com/r/{name}.json",
    "@company-ui": {
      "url": "https://registry.company.com/ui/{name}.json",
      "headers": {
        "Authorization": "Bearer ${COMPANY_TOKEN}"
      }
    },
    "@team": {
      "url": "https://team.company.com/{name}.json",
      "params": {
        "team": "frontend",
        "version": "${REGISTRY_VERSION}"
      }
    }
  }
}

该配置可用于：

安装 shadcn/ui 的公共组件
访问公司私有 UI 组件（含鉴权）
使用团队特定且带版本的资源

关于鉴权的更多说明，请参考 Authentication 文档。

Installation 主题