Back to Details

21st-registry

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Publish & manage on the 21st registry

在21st注册表中发布与管理

Publish components, themes and templates to 21st.dev, and manage what you've already published, all through the unified 
21st
CLI (
@21st-dev/cli
).
通过统一的
21st
CLI（
@21st-dev/cli
），将组件、主题和模板发布到21st.dev，并管理你已发布的所有内容。

Pre-flight (always)

事前准备（必做）

  1. Auth needs a real API key. Publish, edit and delete are management endpoints: they accept a 
    21st_sk_…
    key only, not a 
    21st login
    session token. Get one at https://21st.dev/mcp (or https://21st.dev/settings/api-keys) and pass it via 
    --api-key 21st_sk_…
    or the 
    TWENTYFIRST_TOKEN
    / 
    API_KEY_21ST
    env var. If the user has no key, point them there.
  2. The CLI is the unified 
    @21st-dev/cli
    (bin 
    21st
    ). Don't reinvent — use it.
  3. Search before publishing (
    21st search "<query>"
    ) so you don't add a duplicate to the library.
  1. 认证需要真实的API密钥。发布、编辑和删除属于管理端点：它们仅接受
    21st_sk_…
    密钥，不支持
    21st login
    会话令牌。请前往**https://21st.dev/mcp**（或**https://21st.dev/settings/api-keys**）获取密钥，并通过`--api-key 21st_sk_…
    或
    TWENTYFIRST_TOKEN
    /
    API_KEY_21ST`环境变量传入。如果用户没有密钥，请指引他们前往上述地址。
  2. CLI工具为统一的
    @21st-dev/cli
    （二进制文件名为
    21st
    ）。不要自行开发——直接使用它。
  3. 发布前先搜索（
    21st search "<query>"
    ），避免向库中添加重复内容。

Publish a component

发布组件

The positional file path triggers auto-detection — name from the default export, slug from the filename, tags from imports, demo auto-found or synthesised. In ~95% of cases this is enough:
bash
21st publish ./path/to/Component.tsx \
  --to default \
  --description "1-2 sentences: what it does and when to use it"
传入文件路径将触发自动检测：从默认导出中提取名称、从文件名生成slug、从导入内容提取标签、自动查找或合成演示示例。在约95%的情况下，以下命令足够：
bash
21st publish ./path/to/Component.tsx \
  --to default \
  --description "1-2句话：说明组件功能及适用场景"

Decide visibility — default to unlisted

选择可见性——默认设为未列出

User says…Flag
"share with team", "залей нам", default for any unqualified ask(none — defaults to 
unlisted
)
"shareable link but not listed"
--unlisted
"publish publicly", "make it public on 21st"
--public
"restrict to the team library", "keep it internal"
--private
Never use 
--public
without an explicit "publish publicly". Public components go through admin moderation and appear in the 21st library.
用户指令…参数
"share with team"、"上传给我们"、任何未明确说明的默认请求（无参数——默认设为
unlisted
）
"生成可分享链接但不列入列表"
--unlisted
"公开发布"、"在21st上公开"
--public
"限制在团队库内"、"保持内部可用"
--private
除非用户明确要求"公开发布"，否则绝不要使用
--public
参数。公开组件需要经过管理员审核，并会出现在21st库中。

Flag reference

参数参考

FlagWhen to use
--description "…"
Required, 10+ chars: what it does + when to use it. Never fabricate — read the code or ask the user.
--name
, 
--slug
, 
--tags a,b
Override auto-detected name / URL slug / 1-5 tags.
--demo <file>
Demo file. Auto-found (
{Comp}.demo.tsx
, 
demos/{slug}.tsx
, 
demos/default.tsx
) or a trivial one is synthesised. A real demo gives a much better preview.
--preview <img>
Optional static thumbnail (png/jpg/webp); the library also renders a live iframe.
--registry ui|hooks|blocks|icons
Target sub-registry (default 
ui
).
--to <library-slug>
Target team library (e.g. 
--to default
). Omit for the team's default.
--registry-dep <ref>
Repeatable. A shadcn dep by bare name, URL, or 
@namespace/name
.
--public
/ 
--unlisted
/ 
--private
Visibility (default 
unlisted
).
The command prints the component URL and the install line (
npx @21st-dev/cli add @<handle>/<slug>
).
参数使用场景
--description "…"
必填，长度10字符以上：说明组件功能及适用场景。绝不要编造内容——请阅读代码或询问用户。
--name
, 
--slug
, 
--tags a,b
覆盖自动检测的名称/URL slug/1-5个标签。
--demo <file>
演示文件。会自动查找（
{Comp}.demo.tsx
、
demos/{slug}.tsx
、
demos/default.tsx
）或生成一个简单示例。真实的演示示例能提供更好的预览效果。
--preview <img>
可选的静态缩略图（png/jpg/webp格式）；库中也会渲染实时iframe预览。
--registry ui|hooks|blocks|icons
目标子注册表（默认
ui
）。
--to <library-slug>
目标团队库（例如
--to default
）。省略则使用团队的默认库。
--registry-dep <ref>
可重复使用。通过裸名称、URL或
@namespace/name
指定shadcn依赖。
--public
/ 
--unlisted
/ 
--private
可见性（默认
unlisted
）。
命令执行后会输出组件URL和安装命令（
npx @21st-dev/cli add @<handle>/<slug>
）。

Updating vs a new component

更新组件 vs 发布新组件

Re-run with the same slug → upsert (prints "Updated"). Teammates always get the latest; no version flag. If the user meant a NEW component but the slug collides, confirm before overwriting and suggest a different 
--slug
.
使用相同的slug重新运行命令→更新（输出"Updated"）。团队成员始终获取最新版本；无需版本参数。如果用户本意是发布新组件但slug冲突，请在覆盖前确认，并建议使用不同的
--slug
。

Hard rules for agents

代理程序必须遵守的规则

  • ❌ Never 
    --public
    without an explicit instruction.
  • ❌ Never fabricate a description; never publish a file with API keys, secrets, or unsaved edits (flush first).
  • ✅ Always search first; always ship a useful demo when you can.
  • ❌ 除非有明确指令，否则绝不要使用
    --public
    参数。
  • ❌ 绝不要编造描述内容；绝不要发布包含API密钥、机密信息或未保存编辑的文件（请先保存）。
  • ✅ 始终先进行搜索；尽可能附带实用的演示示例。

Publish a theme

发布主题

A theme is a CSS file that must define both a 
:root
and a 
.dark
block of token values. It publishes as a public community theme.
bash
21st publish-theme ./my-theme.css --name "Midnight" [--tags dark,minimal]
To generate that CSS from the current project's design tokens instead of writing it by hand, use the 
21st-design-sync
skill.
主题是一个CSS文件，必须同时定义
:root
和
.dark
代码块的令牌值。主题将作为公开的社区主题发布。
bash
21st publish-theme ./my-theme.css --name "Midnight" [--tags dark,minimal]
如果不想手动编写CSS，可使用
21st-design-sync
技能，从当前项目的设计令牌生成主题CSS。

Publish a template

发布模板

A template is a metadata listing (URLs, not files). It lands in 
draft
for moderation.
bash
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]
模板是元数据列表（仅包含URL，不包含文件）。发布后会处于
draft
状态，等待审核。
bash
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]

Edit & delete your published items

编辑与删除已发布项目

bash
undefined
bash
undefined

Update YOUR OWN item (owner-only; 404 otherwise).

更新你自己的项目（仅所有者可用；否则返回404）。

21st edit <slug> --type component --visibility public|unlisted|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]
21st edit <slug> --type component --visibility public|unlisted|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:

删除项目。必须使用--yes参数。不同类型项目的语义不同：

component -> unpublished (visibility set to private; reversible via edit/re-publish)

component -> 取消发布（可见性设为private；可通过编辑/重新发布恢复）

theme -> unpublished (removed from the marketplace; reversible)

theme -> 取消发布（从市场移除；可恢复）

template -> PERMANENT hard delete

template -> 永久硬删除

21st delete <id|slug> --type component|theme|template --yes

Notes: template visibility is moderation-controlled (`--visibility` is ignored
for templates). Themes rename via `--name` and only support `public|private`.
Anything the CLI can't do, point the user to their studio at
`https://21st.dev/studio/<username>`.

---
21st delete <id|slug> --type component|theme|template --yes

注意：模板的可见性由审核控制（`--visibility`参数对模板无效）。主题可通过`--name`重命名，仅支持`public|private`可见性。任何CLI无法完成的操作，请指引用户前往其工作室：`https://21st.dev/studio/<username>`。

---

Manage your profile page (bento board)

管理个人资料页面（bento面板）

Your public profile at 
21st.dev/@you
can show a bento-style board of blocks instead of the classic layout. 
set
is a FULL REPLACE (like 
--tags
on 
edit
) — read the current board first if you want to keep existing content.
bash
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
is an array of blocks, top to bottom:
json
[
  { "type": "component", "demoId": 143 },
  { "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`>" }
]
Block types: 
component
(your OWN demoId — from 
21st search --mine
or 
21st get
), 
social
(a link card, icon auto-detected from the domain), 
note
(text), 
hire
/ 
pro
/ 
support
(headline/body/url/email/cta), 
image
(
mediaUrl
from 
profile upload
— a foreign url is dropped, not an error), 
divider
(splits the board into a new section). Every block accepts optional 
w
/
h
(grid units, 1-3 wide / 1-2 tall) to size it.
Reordering = re-post the blocks array in the order you want; the board packs top-to-bottom, left-to-right in array order.
你的公开个人资料页面
21st.dev/@you
可以展示bento风格的模块面板，替代经典布局。
set
命令会完全替换现有内容（类似
edit
命令中的
--tags
参数）——如果要保留现有内容，请先读取当前面板。
bash
21st profile get [--json]                 # 读取当前面板（以模块形式展示）
21st profile set --file board.json        # 替换面板内容（JSON数组，或通过标准输入传入）
21st profile set --clear                  # 恢复为经典（非bento）个人资料
21st profile upload ./cover.png           # 上传png/jpg/gif/webp格式图片，输出图片URL
board.json
是一个模块数组，从上到下排列：
json
[
  { "type": "component", "demoId": 143 },
  { "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/邮箱/号召性用语）、
image
（
mediaUrl
来自
profile upload
——外部URL会被忽略，不会报错）、
divider
（将面板分割为新区域）。每个模块都可选择传入
w
/
h
参数（网格单位，宽度1-3 / 高度1-2）来调整尺寸。
重新排序模块=按所需顺序重新提交模块数组；面板会按数组顺序从上到下、从左到右排列模块。

Teams & config

团队与配置

bash
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|windsurf [--write]   # write MCP config
bash
21st teams                          # 查看你的团队
21st team <teamId>                  # 查看团队的库
21st team-lists <teamId>            # 查看团队的共享书签列表
21st team-components <teamId> [--library <id>]

21st init --client cursor|claude|codex|vscode|windsurf [--write]   # 写入MCP配置