블록 추가하기
블록 추가하기 (Add a block)
블록 라이브러리에 컴포넌트를 기여하는 방법을 설명하는 문서예요. 블록은 단일 컴포넌트 하나일 수도, 대시보드처럼 여러 컴포넌트·훅·유틸이 모인 복합 컴포넌트일 수도 있어요. 커뮤니티가 만든 블록을 공유해 고품질의 재사용 컴포넌트 라이브러리를 함께 키워 봐요.
출처: 문서
본문
블록 라이브러리에 커뮤니티의 기여를 초대하고 있어요. 여러분의 컴포넌트와 블록을 다른 개발자들과 공유해서, 고품질의 재사용 가능한 컴포넌트 라이브러리를 만드는 데 함께해 주세요.
어떤 종류의 블록이든 환영해요: 애플리케이션, 마케팅 페이지, 제품 등 다양하게요.
작업 공간 설정하기
저장소 포크하기 (Fork the repository)
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.com/schema/registry-item.json의 레지스트리 스키마를 따릅니다.
export const blocks = [
// ...
{
name: "dashboard-01",
author: "shadcn (https://ui.shadcn.com)",
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)
categories 속성은 레지스트리에서 블록을 정리하는 데 사용돼요.
카테고리 추가하기
새 카테고리가 필요하면 apps/www/registry/registry-categories.ts의 registryCategories 배열에 추가하면 돼요.
export const registryCategories = [
// ...
{
name: "Input",
slug: "input",
hidden: false,
},
]
가이드라인 (Guidelines)
블록 라이브러리에 기여할 때 지켜야 할 가이드라인이에요.
- 블록 정의에는 다음 속성이 필수예요:
name,description,type,files,categories. - 모든 레지스트리 의존성을
registryDependencies에 나열하세요. 레지스트리 의존성이란 레지스트리에 있는 컴포넌트 이름을 말해요(예:input,button,card). - 모든 의존성을
dependencies에 나열하세요. 의존성이란 레지스트리에 있는 패키지 이름을 말해요(예:zod,sonner). - 블록에 페이지(선택)가 있다면
files배열의 첫 번째 항목이어야 하고target속성을 가져야 해요. 이렇게 하면 CLI가 파일 기반 라우팅에 맞는 위치에 페이지를 배치할 수 있어요. - import는 항상
@/registry경로를 사용하세요. 예:import { Input } from "@/registry/new-york/input"
더 알아보기 (Learn more)
- shadcn/ui 블록 라이브러리 — 배포된 블록 모음