113k
新建

components.json

PreviousNext

你的项目配置。

components.json 文件保存了你项目的配置。

我们用它来理解你的项目是如何设置的，以及如何生成适合你项目的组件。

你可以通过运行以下命令，在项目中创建一个 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

这用于为你的组件生成默认主题 token。初始化后无法更改。

components.json
{
  "tailwind": {
    "baseColor": "neutral" | "stone" | "zinc" | "mauve" | "olive" | "mist" | "taupe"
  }
}

tailwind.cssVariables

我们使用并推荐用 CSS 变量来做主题。

将 tailwind.cssVariables 设为 true 可生成诸如 background、foreground 和 primary 之类的语义化主题 token。将其设为 false 则会生成内联的 Tailwind 颜色工具类。

components.json
{
  "tailwind": {
    "cssVariables": `true` | `false`
  }
}

更多信息请参见 主题文档。

初始化后无法更改。 如果要在 CSS 变量和工具类之间切换，你需要删除并重新安装组件。

tailwind.prefix

Tailwind CSS 工具类使用的前缀。添加组件时会使用这个前缀。

components.json
{
  "tailwind": {
    "prefix": "tw-"
  }
}

rsc

是否启用 React Server Components 支持。

当设为 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 文件中设置好。

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 组件
  • 使用带版本管理的团队专属资源

有关身份验证的更多信息，请参阅 身份验证 文档。