介绍

开始使用

表单

注册表

components.json

您项目的配置文件。

components.json 文件包含您项目的配置信息。

我们使用它来了解您的项目如何设置，以及如何为您的项目生成定制组件。

注意：`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

用于帮助 CLI 理解您项目中 Tailwind CSS 如何配置的设置。

有关 Tailwind CSS 的安装方法，请参见安装章节。

tailwind.config

tailwind.config.js 文件所在路径。对于 Tailwind CSS v4 版本，请留空。

components.json

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

tailwind.css

引入 Tailwind CSS 的 CSS 文件路径。

components.json

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

tailwind.baseColor

用于生成组件默认颜色调色板。初始化后不可更改。

components.json

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

tailwind.cssVariables

可选择使用 CSS 变量或 Tailwind CSS 实用类进行主题定制。

若想使用实用类主题，将 tailwind.cssVariables 设为 false；使用 CSS 变量则设为 true。

components.json

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

更多详情请参见主题文档。

初始化后不可更改。 若要在 CSS 变量和实用类之间切换，需删除并重新安装您的组件。

tailwind.prefix

Tailwind CSS 实用类前缀。组件会使用该前缀添加类名。

components.json

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

rsc

是否启用 React 服务器组件支持。

设置为 true 时，CLI 会自动向客户端组件添加 use client 指令。

components.json

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

tsx

选择使用 TypeScript 还是 JavaScript 组件。

将此选项设为 false，组件将以 JavaScript .jsx 文件格式添加。

components.json

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

aliases

CLI 使用此配置和您 tsconfig.json 或 jsconfig.json 中的 paths 配置，将生成的组件放置到正确位置。

路径别名需在您的 tsconfig.json 或 jsconfig.json 中设置。

重要提示： 如果您使用 src 目录，确保它已包含在您的 tsconfig.json 或 jsconfig.json 文件的 paths 设置中。

aliases.utils

工具函数的导入别名。

components.json

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

aliases.components

组件的导入别名。

components.json

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

aliases.ui

ui 组件的导入别名。

CLI 会根据 aliases.ui 的配置决定将 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 组件
使用团队特定资源并支持版本管理

有关鉴权的更多信息，请参见鉴权文档。

安装主题定制