21st-registry

在 21st 注册表上发布和管理

通过统一的 21st CLI（@21st-dev/cli）将组件、主题和模板发布到 21st.dev，并管理已发布的内容。

发布前准备（始终执行）

1. 发布前先进行身份验证。 组件发布、内容清单、检出、元数据编辑和取消发布，均可使用 21st login 会话或 21st_sk_… API 密钥。主题和模板命令仍需要来自 https://21st.dev/settings/api-keys 的真实 API 密钥，并通过 --api-key、TWENTYFIRST_TOKEN 或 API_KEY_21ST 传入。
2. CLI 是统一的 @21st-dev/cli（可执行文件名为 21st）。不要另造工具，使用它即可。
3. 发布前先搜索（21st search "<query>"），避免向库中添加重复内容。

---

查找现有组件和草稿

当用户要求继续或编辑旧的组件工作时，从这里开始：

21st components
21st components --status draft --scope personal --json
21st open component:123
21st open draft:<uuid> --no-open

默认情况下，21st components 会分别获取两个可独立分页的集合，因此不加筛选时，会返回所有可访问的个人或 Team 组件，以及所有归用户所有的草稿。使用 --status all|draft|published|private 或 --scope all|personal|team:<uuid> 缩小范围。保留返回的稳定引用 component:<id> 或 draft:<uuid>；不要用 slug 替代。

21st open draft:<uuid> 会恢复可编辑的 Studio 草稿。21st open component:<id> 会根据保留的已发布组件代码和演示，创建或恢复由服务端管理的 CLI Review 修订版。该修订版发布前，线上组件不会改变。必须使用新封面；可选的视频生成会在后台尽力完成。--no-open 会创建或恢复工作区并打印其 URL，但不会启动浏览器。

如果源文件已经更改，请使用本地文件：

21st publish ./Component.tsx \
  --component component:123 \
  --description "What changed"

切勿用同 slug 的猜测值替换稳定引用。只有原组件作者才能检出代码。Team 管理员仍可通过稳定引用编辑或取消发布队友组件的元数据。

如果保留的源代码、依赖项、样式、支持文件或默认演示无法安全复现，检出操作会安全失败。请改用上面的本地源代码命令，不要放宽检查条件或声称可以访问代码。

登录会话可以列出个人内容，以及用户有权管理的 Teams。个人密钥仅限个人使用；Team 密钥仅限对应的 Team 使用。新的 CLI Review 草稿会保留已验证身份的个人或 Team／库范围。有证明支持的旧版 CLI 草稿会恢复到相符的已验证身份范围。无法证明范围的较早无签名草稿可能需要重新创建。

---

发布组件

位置参数中的文件路径会触发自动检测：名称取自导出的组件，slug 取自文件名，标签取自导入内容，演示则会自动查找或合成。对于新的 slug 或归用户所有的修订版，该命令会验证依赖项、安装并构建组件、创建 Studio 草稿、打开专属的 CLI Review，然后等待。Review 侧栏会显示准确的 Demos (N) 数量，并在实时预览旁保留所选演示。Studio 会先生成必需的封面，再在后台尝试生成可选视频。归用户所有的修订版会保持待处理状态，直到完成相同的 CLI Review 并发布。

21st publish ./path/to/Component.tsx \
  --to default \
  --description "1-2 sentences: what it does and when to use it"

决定访问权限 — 默认设为 Published

用户说……	标记
“发布”、“分享链接”，或任何未明确说明的请求的默认情况	(无 — 默认设为 published)
“提交到目录”、“争取精选”	发布后运行 21st submit <slug>
“限制在团队库中”、“仅供内部使用”	--private

发布操作只控制访问权限。精选收录始终是单独的审核操作，因此发布不会在未告知的情况下提交组件。

标志参考

标志	使用时机
--description "…"	必填，至少 10 个字符：说明功能及适用场景。切勿捏造——请阅读代码或询问用户。
--name、--slug、--tags a,b	覆盖自动检测的名称／URL slug／1-5 个标签。
--demo <file>	演示文件。会自动查找（{Comp}.demo.tsx、demos/{slug}.tsx、demos/default.tsx），或合成一个简单文件。真实演示可显著改善预览效果。
--preview <img>	设置初始封面图片。该图片会替换生成的封面，但不能绕过 Studio 审核或必需封面的检查。
--no-open	打印 Studio 草稿 URL，但不打开。草稿仍可供之后审核。
--registry ui|hooks|blocks|icons	目标子注册表（默认为 ui）。
--to <library-slug>	目标团队库（例如 --to default）。省略时使用团队默认库。
--registry-dep <ref>	CLI Review 暂不支持。创建新组件或自有修订版前，请移除此项。
--visibility published|private	访问权限（默认为 published）。

对于新 slug 或自有修订版，该命令会打印 Studio 草稿 URL；只有 Studio 发布后，才会报告组件 URL 和安装命令。 按下 Ctrl+C 会停止 CLI 等待，但保留草稿。

为演示添加可交互控件（访客可操作的旋钮面板）

此功能没有对应的标志：控件由演示自身的代码决定。声明一个模块级 settings 对象，并让默认导出接收 props，发布流水线就会在预览旁生成一个实时面板。访客调整旋钮后，点击“Copy code”即可获取将其值写回 settings 字面量的代码，因此，可配置的演示远比静态演示有价值。凡是有可调值的内容都可以这样处理——粒子数量、速度、颜色、大小、标签、功能标志。

const settings = {
  particleCount: 1000,
  speed: 0.4,
  showGrid: true,
  glowColor: "#7dd3fc",
  palette: ["#0ea5e9", "#f472b6"],
  headline: "Ship faster",
}

export default function Demo(props: Partial<typeof settings>) {
  const s = { ...settings, ...props }
  return <Hero count={s.particleCount} speed={s.speed} ... />
}

这两部分缺一不可。没有 props 的设置（或没有设置的 props）都不会生成面板，因为会动却不影响任何东西的旋钮还不如没有。

根据值本身推断的标签和范围（particleCount ->“Particle Count”）如下：

settings 中的值	控件
数字	滑块（整数 -> 0..3x；0..1 浮点数 -> 比例滑块）
布尔值	开关
CSS 颜色字符串（#7dd3fc、oklch(...)）	颜色选择器
颜色字符串数组（<= 12）	可编辑调色板
其他字符串，<= 120 个字符	文本字段
嵌套对象、混合数组、长字符串	无控件——请将其展开为顶层键

编写此对象前，请注意以下规则：控件最多 24 个；键必须是普通标识符，且不能是 key、ref、constructor、prototype 或 __proto__；值必须是流水线可读取的字面量（settings 对象中不能包含导入的常量、计算表达式或展开语法）；Expo / 原生演示完全不会生成面板。

推断出的标签和范围只是估值，可按需修正。在 CLI Review 中，Controls 区块会渲染访客将看到的同一面板——请检查面板，然后在最终发布前重命名标签并收紧 min/max/step。编辑这些内容不会改变值：这些值始终会从你实际发布的代码中重新读取。

新 slug 或自有修订的必需 Agent 审核

构建门禁会捕获未声明的包、安装失败、无法解析的导入和编译错误。但它无法证明渲染后的 UI、交互或颜色在视觉上正确。最终发布前，请先完成以下步骤：

1. 确保组件和演示自包含。在最近的 package.json 中声明每个导入的 npm 包；不要留下无法解析的本地导入或别名导入。确认 CLI 构建成功后再继续。目前的 CLI 命令只会发送一个组件文件和一个演示；暂不接受其他本地文件和 21st.json。
2. 使用可移植的 Tailwind 语义令牌，例如 bg-primary、text-primary-foreground、bg-background 和 border-border。在自定义 CSS 或任意属性中，使用 Tailwind v4 主题变量，例如 var(--color-primary) 和 var(--color-muted-foreground)。
3. 切勿写成 oklch(var(--primary))、hsl(var(--primary))，也不要以其他方式假设 --primary 等原始变量的存储格式。项目可能存储通道元组，而 Studio 存储完整的 CSS 颜色。需要设置不透明度时，使用 bg-primary/20 等工具类，或将 var(--color-primary) 与 color-mix() 搭配使用。
4. Studio 打开后，使用专用的 CLI Review。确认 Demos (N) 的数量，选择每个演示，并检查右侧的实时预览。测试每种有意义的状态，并验证浅色和深色主题，包括语义主色是否能正确解析。如果演示声明了 settings，也要操作 Controls 面板：每个控件都必须能明显改变预览，且其标签和范围必须合理。
5. 如果预览空白、报错、存在无法解析的依赖，或颜色不正确，请修复源文件并再次运行 21st publish。不要仅为让预览通过而硬编码源项目的品牌颜色。
6. 最终发布前，请等待自动生成 Cover。封面生成优先级最高，且仍是发布的硬性门禁。可选视频会在后台尽力生成：发布不会等待视频完成，只有视频就绪时才会将其加入。如果生成的任一素材不具代表性，请手动替换。 生成的媒体不能代替对实时组件的审核。

更新现有组件还是新建组件

先盘点。使用 21st open component:<id>，从保留的已发布代码和演示创建或继续已审核的修订。如果源文件已在本地更改，则改用 21st publish <file> --component component:<id>。修订完成 CLI Review 并发布之前，当前线上版本不会改变。如果用户想新建组件，但 slug 冲突，请在继续前确认，并建议使用其他 --slug。

Agent 硬性规则

• 切勿捏造描述，也不要发布包含 API 密钥、机密或未保存编辑内容的文件。
• 对于现有内容，先盘点并使用其稳定引用；不要根据 slug 猜测。
• 始终先搜索，提供实用的演示（只要存在可调整的值，就通过 settings 控制），验证构建和依赖，完成上述实时预览和主题令牌审核，并等待必需的封面生成后再最终发布。

---

发布主题

主题是一个 CSS 文件，必须同时定义包含令牌值的 :root 和 .dark 块。发布后，它会成为公开的社区主题。

21st publish-theme ./my-theme.css --name "Midnight" [--tags dark,minimal]

如需根据当前项目的设计令牌生成 CSS，而非手动编写，请使用 21st-design-sync 技能。

发布模板

模板是元数据列表（包含 URL，而非文件）。发布后会进入 draft，等待审核。

21st publish-template "SaaS Starter" \
  --site https://demo.example.com \
  --preview https://example.com/thumb.png \
  [--description "…"] [--price 49] [--buy-url https://…] [--video https://…] [--tags 1,2]

---

编辑和删除已发布的内容

# Update an exact component from inventory. A Team manager may manage metadata.
21st edit component:<id> --type component --visibility published|private \
  [--description "…"] [--tags a,b]
21st edit <theme-id> --type theme [--visibility public|private] [--name "New Name"] [--tags a,b]
21st edit <template-id> --type template [--name N] [--description D] [--tags 1,2]

# Remove an item. ALWAYS requires --yes. Semantics differ by type:
#   component -> unpublished (visibility set to private; reversible via edit/re-publish)
#   theme     -> unpublished (removed from the marketplace; reversible)
#   template  -> PERMANENT hard delete
21st delete component:<id> --type component --yes
21st delete <id> --type theme|template --yes

# Catalog review is independent from Published/Private access.
21st submit <slug>
21st withdraw <slug>
21st resubmit <slug>
21st remove-from-catalog <slug>

注意：模板的可见性由审核控制（模板会忽略 --visibility）。主题通过 --name 重命名，且仅支持 public|private。编辑/删除组件可使用登录会话或 API 密钥；管理主题/模板仍需要 API 密钥。要在浏览器中编辑，请先盘点内容，然后运行 21st open <stable-ref>。如果无法安全检出保留的组件源代码，请改用 21st publish <file> --component component:<id> 创建经过审核的代码修订。

---

管理个人资料页面（便当板）

你在 21st.dev/@you 的公开个人资料可以显示便当风格的区块板，而不是经典布局。set 会完全替换内容（类似 edit 上的 --tags）——如果想保留现有内容，请先读取当前的区块板。

21st profile get [--json]                 # read your current board (as blocks)
21st profile set --file board.json        # replace it (JSON array, or pipe it via stdin)
21st profile set --clear                  # revert to the classic (non-bento) profile
21st profile upload ./cover.png           # upload a png/jpg/gif/webp, prints a url

board.json 是一个区块数组，顺序从上到下：

[
  { "type": "component", "demoId": 143 },
  { "type": "library", "refId": "<personal-or-team-library-id>" },
  { "type": "social", "url": "https://x.com/you" },
  { "type": "note", "text": "Building UI for 21st.dev" },
  { "type": "hire", "headline": "Work with me", "url": "https://cal.com/you" },
  { "type": "divider" },
  { "type": "image", "mediaUrl": "<url from `profile upload`>" }
]

区块类型：component（你自己的 demoId——来自 21st search --mine 或 21st get）、social（链接卡片，图标会根据域名自动检测）、note（文本）、hire / pro / support（标题/正文/url/email/cta）、library（通过 refId 指定的公开个人或团队库）、image（来自 profile upload 的 mediaUrl——外部 url 会被丢弃，不会报错）、divider（将区块板分隔为新的分区）。每个区块都可选用 w/h（网格单位，宽 1-3 格 / 高 1-2 格）设置尺寸。

要重新排序，请按所需顺序重新发布区块数组；区块板会按照数组顺序从上到下、从左到右排列。

团队和配置

21st teams                          # your teams
21st team <teamId>                  # a team's libraries
21st team-lists <teamId>            # a team's shared bookmark lists
21st team-components <teamId> [--library <id>]

21st init --client cursor|claude|codex|vscode|devin [--write]      # write MCP config