21st-registry

在 21st 团队库中发布和安装组件

将此技能用于两个方向：为团队发布组件，以及安装团队已分享的组件。

发布前检查（始终执行）

1. 检查身份验证：API_KEY_21ST 环境变量已设置，或注册表 CLI 已保存凭据。如果两者都没有，请告知用户运行一次 npx @21st-dev/registry login。不要尝试自行帮用户登录。
2. CLI 是 @21st-dev/registry。不要另起炉灶，直接使用它。

---

发布组件

决定可见性——在注册表中默认设为未列出

用户说……	可见性
“与团队分享”“залей нам”“内部发布”，或任何未明确说明的请求	在选定的／默认注册表中设为未列出（无需可见性标志）
“通过链接公开分享／发布到我的个人主页，但不要列入库中”	--unlisted
“公开发布”“在 21st 上公开”	--public
“限制为注册表团队可见”“私有团队草稿”	--private

**未经用户明确指示，绝不要使用 --public。**公开组件需要经过管理员审核，并会显示在 21st 库中。如果用户希望获得可分享的 URL，但不想将组件列入库中，--unlisted 是安全的选择。

标准发布

CLI 会根据位置文件路径自动检测：从默认导出获取名称、从文件名获取 slug、从导入获取标签，并自动查找或生成演示。因此，95% 的情况下只需执行以下命令：

npx @21st-dev/registry ./path/to/Component.tsx \
  --to default \
  --description "1-2 sentences about what it does and when to use it"

标志参考

标志	使用时机
--name "Display Name"	覆盖自动检测到的名称。默认值是根据默认导出名称转换成的易读名称。
--description "…"	**必填。**至少 10 个字符。请如实描述组件的功能和适用场景。切勿编造；如果不了解，请询问用户。
--tags "form,input,validation"	1–5 个小写标签。默认值：根据导入内容检测（lucide-react → “icon”，framer-motion → “animation”，等等）。只有自动检测的标签不恰当时才覆盖。
--slug my-button	覆盖 URL slug。默认值是根据名称转换成的 kebab-case。
--demo ./Component.demo.tsx	演示文件。自动检测以下格式：{Component}.demo.tsx、demos/{slug}.tsx、demos/default.tsx。如果都不存在，CLI 会自动生成一个简单的 <Component /> 演示——用于 v1 没问题，但真实演示能提供好得多的预览。
--preview ./preview.png	**可选。**团队库使用实时 iframe 预览；只有想要加载迅速的缩略图时才需要静态图片。
--to <registry-slug>	指定已通过身份验证的团队中的某个注册表（例如 --to default）。如果省略，服务器会使用团队的第一个／默认注册表。
--public / --unlisted / --private	覆盖组件可见性。

用户会收到什么

✅ https://21st.dev/community/components/{username}/{slug}
Install in another project:
  npx @21st-dev/registry add @{username}/{slug}

更新现有组件

使用相同命令和相同 slug，即可更新或创建。CLI 会打印“Updated”而不是“Published”。无需版本标志；团队成员始终能获取最新版本。

如果用户说“我想要一个新组件，不是更新现有组件”，但 slug 已被占用，请先与用户确认再覆盖；建议更改 --slug。

安装组件

接受两种地址格式：

• @team-slug/component-slug — 从团队注册表安装（团队共享时首选）
• @username/component-slug — 从用户的个人／公开组件中安装

npx @21st-dev/registry add @acme/animated-button
# or
npx @21st-dev/registry add @serjobas/animated-button

CLI 会：

1. 获取注册表 JSON 和组件文件（服务端会先将 @handle 解析为 team-slug，再解析为 username）
2. 将其写入项目（默认写入 components/ui/{slug}.tsx）
3. 对任何 npm 依赖运行 pnpm/npm/yarn/bun add
4. 如果组件依赖其他 21st 组件，则会列出这些组件——请单独使用 add 安装

对于直接使用 shadcn 的情况，公开／未列出的组件可以使用普通的注册表条目 URL：

npx shadcn@latest add "https://21st.dev/r/acme/animated-button"

对于重复安装或私有组件，请在使用方项目的 components.json 中注册 21st 注册表，并使用 Bearer 令牌：

{
  "registries": {
    "@YOUR_NAMESPACE": {
      "url": "https://21st.dev/r/acme/default/{name}.json",
      "headers": {
        "Authorization": "Bearer ${API_KEY_21ST}"
      }
    }
  }
}

然后使用 shadcn CLI 的标准命令进行安装：

npx shadcn@latest add @YOUR_NAMESPACE/animated-button

@YOUR_NAMESPACE 只是 components.json 中的本地别名；请使用任何清晰易懂的 slug。除非用户明确希望该本地文件包含个人密钥，否则不要将真实 API 密钥提交到 components.json。

标志：

• --force — 覆盖现有文件
• --no-install — 跳过 npm 安装步骤（仅写入文件）
• --dir PATH — 安装到其他项目目录

---

搜索团队库

当用户想要一个组件，但不知道确切名称时：

npx @21st-dev/registry search "<query>"

默认范围是 team（团队库）。使用 --scope mine 仅搜索你自己的组件，使用 --scope public 搜索公开库。

如果可能已存在类似组件，发布前务必先搜索。 不要向团队库添加重复组件。

npx @21st-dev/registry search "button" --scope team
# Prints list with @user/slug refs you can pass to `add`.

---

管理团队和注册表

可以通过 CLI 查看、创建和编辑团队及注册表（不能删除——删除操作 仍需在 Web Studio 中进行）。每个子命令都接受 --json；需要解析 输出时优先使用它。团队通过 slug 指定，使用 --team <slug> （默认值：API 密钥所属的团队）。

# Inspect before acting
npx @21st-dev/registry team list --json            # all teams: slug, role, default
npx @21st-dev/registry team info [team]            # members + pending invites
npx @21st-dev/registry registry list --team <slug> --json

# Create
npx @21st-dev/registry team create "<name>" [--description TEXT]
npx @21st-dev/registry registry create "<name>" [--slug SLUG] [--description TEXT] [--team SLUG]
# registry slug is auto-derived from the name if --slug is omitted

# Edit
npx @21st-dev/registry team edit [team] --name TEXT --description TEXT   # owner only
npx @21st-dev/registry registry edit <slug> --name TEXT --description TEXT

# Invite a collaborator by email
npx @21st-dev/registry team invite <email> [--team SLUG]

发布一组新组件前的典型流程：使用 registry list --json 查看现有内容 → 如有需要，运行 registry create "Marketing blocks" → 运行 publish --to marketing-blocks。

---

Agent 的硬性规则

• ❌ 绝不要在用户未明确要求“公开发布”的情况下使用 --public。
• ❌ 绝不要编造描述。请询问用户，或仔细阅读代码。
• ❌ 绝不要在要发布的组件文件中包含 API 密钥、环境变量值或硬编码的内部 URL。
• ❌ 绝不要发布包含未保存修改的文件——请先保存。
• ✅ 如果可能已存在类似组件，发布前务必先搜索。
• ✅ 如果可以，请务必添加带有真实 props 的实用演示文件；只有最后才考虑使用自动合成的演示文件。

需要避免的常见错误

1. 演示文件通过错误路径导入组件。 CLI 会在上传前自动将相对导入（例如 import X from "../component"）改写为 @/components/ui/{slug}——因此，请在演示文件中使用指向用户源文件的相对导入，而不是别名。CLI 会处理好。
2. 多次发布时 slug 不一致。 如果用户重命名文件，自动生成的 slug 也会改变，从而创建重复组件。使用稳定名称重新发布时，请显式传入 --slug。
3. 组件没有默认导出。 这会导致明确的错误——请先将组件重构为 export default function ComponentName(...)。