Items 工程能力

概述

Items 用于分发工程模板、配置文件与工具类代码（例如 make-api-request、zustand）。它们通常输出一组目标文件，帮助项目快速对齐网络层、状态管理或静态检查等工程基建。

创建 Item 模板

1. 生成基础目录

bun run registry:create <name> --type item

生成目录示例：

registry/ssp/item/<name>/
├── index.json        # 元数据（必填）
├── README.mdx        # 文档（必须补充）
└── example/          # 示例或脚手架代码（可选）
    └── ...

名称需为 kebab-case，且与 index.json 中的 name 字段一致。

2. 安装依赖（如需要）

bun add <package-name>

将依赖写入 index.json 的 dependencies 字段，例如：

registry/ssp/item/zustand/index.json

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "zustand",
  "type": "registry:item",
  "dependencies": ["zustand"],
  "files": [
    {
      "path": "registry/ssp/item/zustand/index.ts",
      "type": "registry:file",
      "target": "store/global.ts"
    }
  ]
}

配置 index.json

index.json 是 Item 的核心元数据，请确保字段完整：

name：与目录名一致的 kebab-case 名称。
type：固定为 registry:item。
dependencies：安装后的 npm 包列表（带版本可选）。
registryDependencies：依赖的其它 Registry 模块，可填写内部或外部的 JSON URL。例如 make-api-request 依赖 use-cancelable-swr。
files：描述要分发的文件，字段包括：
- path：仓库中的源文件相对路径。
- target：落地到消费者项目时的目标路径。
- type：默认为 registry:file。

示例：

registry/ssp/item/make-api-request/index.json

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "make-api-request",
  "type": "registry:item",
  "dependencies": ["zod"],
  "registryDependencies": [
    "<PUBLIC_REGISTRY_WEBSITE>/r/use-cancelable-swr.json"
  ],
  "files": [
    {
      "path": "registry/ssp/item/make-api-request/base.ts",
      "type": "registry:file",
      "target": "services/base.ts"
    },
    {
      "path": "registry/ssp/item/make-api-request/example/index.ts",
      "type": "registry:file",
      "target": "services/example/index.ts"
    }
  ]
}

编写能力实现

在模块目录内补充 index.ts、base.ts 或需要分发的模板文件。
如果包含示例，放入 example/ 子目录，命名清晰（例如 index.schema.ts、index.template.ts）。
保持导出的代码使用 TypeScript 严格模式，必要时使用 Zod 校验输入输出。

建议将可复用逻辑抽离为纯函数，示例代码只负责演示集成方式。

补充 README 文档

README.mdx 至少包含安装指引和能力说明：

registry/ssp/item/<name>/README.mdx

---
title: <display-name>
---

## 安装

<RegistryDownload filename="<name>.json" />

## 功能概览

- 功能点描述
- 使用前置条件

可结合 ExampleCode 或 Callout 组件展示使用方式。

生成站点文档

运行文档脚本生成基础页面：

bun run registry:gen-doc <name> --type item

在 content/docs/ssp/(item)/<name>.mdx 中补充示例、API 说明、最佳实践等内容。参考现有的 make-api-request、biome 文档确保结构一致。

测试与同步

在提交前执行以下命令：

bun run registry:sync
bun run registry:build
bun run lint

registry:sync 会刷新根目录的 registry.json 与 public/r/ 下的索引文件。
registry:build 验证打包输出是否正常。
lint 使用 Biome 进行类型与格式检查。

提交要求清单

index.json 字段完整，路径与目标文件正确。
示例代码可直接运行，导出的能力具备类型提示。
README 与站点文档覆盖安装、使用、最佳实践。
已执行同步与构建脚本，无额外脏文件。
PR 描述包含新增文件说明与测试结果。

完成后，可返回文档生成与同步指南了解如何发布变更。