我们邀请社区为区块库贡献。与开发者分享您的组件和区块,帮助构建一个高质量、可复用的组件库。
我们希望看到各种类型的区块:应用程序、营销、产品等等。
设置您的工作区
派生仓库
git clone https://github.com/shadcn-ui/ui.git
创建新分支
git checkout -b username/my-new-block
安装依赖
pnpm install
启动开发服务器
pnpm www:dev
添加区块
一个区块可以是一个单独的组件(例如,UI 组件的变体),也可以是一个包含多个组件、钩子和工具的复杂组件(例如,一个仪表盘)。
创建新区块
在apps/www/registry/new-york/blocks
目录中创建一个新文件夹。确保文件夹名称采用 kebab-case 格式,并且位于new-york
之下。
apps
└── www
└── registry
└── new-york
└── blocks
└── dashboard-01
注意:构建脚本将负责为default
样式构建区块。
添加您的区块文件
将您的文件添加到区块文件夹。以下是一个包含页面、组件、钩子和工具的区块示例。
dashboard-01
└── page.tsx
└── components
└── hello-world.tsx
└── example-card.tsx
└── hooks
└── use-hello-world.ts
└── lib
└── format-date.ts
注意:您可以从一个文件开始,稍后添加更多文件。
将您的区块添加到注册表
将您的区块定义添加到registry-blocks.tsx
要将您的区块添加到注册表,您需要将区块定义添加到registry-blocks.ts
。
这遵循位于https://ui.shadcn.org.cn/schema/registry-item.json的注册表架构。
export const blocks = [
// ...
{
name: "dashboard-01",
author: "shadcn (https://ui.shadcn.org.cn)",
title: "Dashboard",
description: "A simple dashboard with a hello world component.",
type: "registry:block",
registryDependencies: ["input", "button", "card"],
dependencies: ["zod"],
files: [
{
path: "blocks/dashboard-01/page.tsx",
type: "registry:page",
target: "app/dashboard/page.tsx",
},
{
path: "blocks/dashboard-01/components/hello-world.tsx",
type: "registry:component",
},
{
path: "blocks/dashboard-01/components/example-card.tsx",
type: "registry:component",
},
{
path: "blocks/dashboard-01/hooks/use-hello-world.ts",
type: "registry:hook",
},
{
path: "blocks/dashboard-01/lib/format-date.ts",
type: "registry:lib",
},
],
categories: ["dashboard"],
},
]
请确保您添加了 name、description、type、registryDependencies、dependencies、files 和 categories。我们将在架构文档(即将推出)中更详细地介绍这些内容。
运行构建脚本
pnpm registry:build
注意:您无需为每个更改运行此脚本。您只需在更新区块定义时运行它。
查看您的区块
构建脚本完成后,您可以在http://localhost:3333/blocks/[CATEGORY]
查看您的区块,或在http://localhost:3333/view/styles/new-york/dashboard-01
查看全屏预览。


构建您的区块
您现在可以通过编辑区块文件夹中的文件并在浏览器中查看更改来构建您的区块。
如果您添加了更多文件,请确保将其添加到区块定义中的files
数组中。
发布您的区块
准备好发布您的区块后,您可以向主仓库提交拉取请求。
运行构建脚本
pnpm registry:build
捕获屏幕截图
pnpm registry:capture
注意:如果您之前运行过捕获脚本,您可能需要删除apps/www/public/r/styles/new-york
处的现有屏幕截图(包括浅色和深色),然后再次运行该脚本。
提交拉取请求
提交您的更改并向主仓库提交拉取请求。
您的区块将被审查和合并。合并后,它将发布到网站并通过 CLI 安装。
类别
categories
属性用于在注册表中组织您的区块。
添加类别
如果您需要添加新类别,可以通过将其添加到apps/www/registry/registry-categories.ts
文件中的registryCategories
数组中来完成。
export const registryCategories = [
// ...
{
name: "Input",
slug: "input",
hidden: false,
},
]
指南
以下是为区块库贡献时应遵循的一些指南。
- 区块定义需要以下属性:
name
、description
、type
、files
和categories
。 - 请确保在
registryDependencies
中列出所有注册表依赖。注册表依赖是注册表中组件的名称,例如input
、button
、card
等。 - 请确保在
dependencies
中列出所有依赖。依赖是注册表中包的名称,例如zod
、sonner
等。 - 如果您的区块包含页面(可选),它应该是
files
数组中的第一个条目,并且应该具有target
属性。这有助于 CLI 将页面放置在基于文件的路由的正确位置。 - 导入应始终使用
@/registry
路径。 例如:import { Input } from "@/registry/new-york/input"