components.json 配置

    components.json 文件用于配置你的项目，使 Codebase Kit 能够理解你的项目设置并生成定制化组件。

    注意

    components.json 文件是可选的，仅在使用 CLI 添加组件时才需要。如果你使用复制粘贴的方式，则不需要此文件。

    初始化

    你可以使用以下命令在项目中创建 components.json 文件：

    npm
    yarn
    pnpm
    bun
    deno
    npx shadcn@latest init

    $schema

    $schema 属性用于指定 components.json 文件的 JSON Schema。

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

    style

    组件的样式风格。初始化后无法更改此配置。

    components.json
    {
  "style": "default"
}

    Codebase Kit 基于 UnoCSS 和 Ant Design 构建，提供了简洁的默认样式和主题系统。

    framework

    指定使用的框架类型。

    components.json
    {
  "framework": "react"
}

    目前 Codebase Kit 支持 React 框架。

    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": "@/components"
  }
}

    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 组件
    • 使用带版本控制的团队特定资源

    完整示例

    以下是一个完整的 components.json 配置示例：

    components.json
    {
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "default",
  "framework": "react",
  "aliases": {
    "utils": "@/lib/utils",
    "components": "@/components",
    "ui": "@/components",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "@codebase-kit": "https://codebase.anyask.dev/r/{name}.json"
  }
}

    tsconfig.json 配置

    为了使路径别名正常工作，你还需要在 tsconfig.json 中配置路径映射：

    tsconfig.json
    {
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/hooks/*": ["./src/hooks/*"]
    }
  }
}