registry-item.json 스키마

registry-item.json 스키마

나만의 컴포넌트 레지스트리 항목을 정의할 때 사용하는 게 바로 registry-item.json 스키마예요. 레지스트리의 각 항목이 어떤 구조로 생겼는지 이 파일이 결정해요. 아래 예시를 보면 전체적인 감이 바로 잡힐 거예요.

출처: 문서

본문

registry-item.json 스키마는 커스텀 레지스트리 항목을 정의할 때 사용돼요.

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "hello-world",
  "type": "registry:block",
  "title": "Hello World",
  "description": "A simple hello world component.",
  "files": [
    {
      "path": "registry/hello-world/hello-world.tsx",
      "type": "registry:component"
    },
    {
      "path": "registry/hello-world/use-hello-world.ts",
      "type": "registry:hook"
    }
  ]
}

정의 (Definitions)

registry-item.json의 JSON Schema는 여기에서 직접 확인할 수 있어요.

$schema

$schema 속성은 registry-item.json 파일이 따르는 스키마를 지정하는 데 사용돼요.

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json"
}

name

name 속성은 레지스트리 항목의 이름을 지정하는 데 사용돼요.

{
  "name": "hello-world"
}

title

title은 레지스트리 항목의 사람이 읽을 수 있는 제목이에요. 짧고 설명적으로 유지하는 게 좋아요.

{
  "title": "Hello World"
}

description

description은 레지스트리 항목에 대한 설명이에요. title보다 길고 상세하게 쓸 수 있어요.

{
  "description": "A simple hello world component."
}

type

type 속성은 레지스트리 항목의 유형을 지정하는 데 사용돼요.

{
  "type": "registry:block"
}

지원되는 유형은 다음과 같아요:

유형	설명
registry:block	여러 파일로 구성된 복잡한 컴포넌트에 사용해요.
registry:component	단순한 컴포넌트에 사용해요.
registry:lib	lib와 utils에 사용해요.
registry:hook	훅에 사용해요.
registry:ui	UI 컴포넌트와 단일 파일 프리미티브에 사용해요.
registry:page	페이지 또는 파일 기반 라우트에 사용해요.
registry:file	기타 다양한 파일에 사용해요.

author

author 속성은 레지스트리 항목의 작성자를 지정하는 데 사용돼요. 레지스트리 항목에만 고유하게 쓸 수도 있고, 레지스트리의 작성자와 같게 쓸 수도 있어요.

{
  "author": "John Doe <[email protected]>"
}

dependencies

dependencies 속성은 레지스트리 항목의 의존성을 지정하는 데 사용돼요. 여기서는 npm 패키지를 대상으로 해요. @version을 사용하면 레지스트리 항목의 버전도 지정할 수 있어요.

{
  "dependencies": [
    "@radix-ui/react-accordion",
    "zod",
    "lucide-react",
    "[email protected]"
  ]
}

registryDependencies

레지스트리 의존성을 지정할 때 사용해요. 이름(name)이나 URL을 쓸 수 있어요.

• button, input, select 같은 shadcn/ui 레지스트리 항목이라면 이름을 쓰면 돼요. 예: ['button', 'input', 'select'].
• 커스텀 레지스트리 항목이라면 레지스트리 항목의 URL을 쓰면 돼요. 예: ['https://example.com/r/hello-world.json'].

{
  "registryDependencies": [
    "button",
    "input",
    "select",
    "https://example.com/r/editor.json"
  ]
}

참고로 CLI는 원격 레지스트리 의존성을 자동으로 해석해요.

files

files 속성은 레지스트리 항목의 파일들을 지정하는 데 사용돼요. 각 파일은 path, type, 그리고 target(선택) 속성을 가져요.

target 속성은 registry:page와 registry:file 유형에서 필수예요.

{
  "files": [
    {
      "path": "registry/hello-world/page.tsx",
      "type": "registry:page",
      "target": "app/hello/page.tsx"
    },
    {
      "path": "registry/hello-world/hello-world.tsx",
      "type": "registry:component"
    },
    {
      "path": "registry/hello-world/use-hello-world.ts",
      "type": "registry:hook"
    },
    {
      "path": "registry/hello-world/.env",
      "type": "registry:file",
      "target": "~/.env"
    }
  ]
}

path

path 속성은 레지스트리에 있는 파일의 경로를 지정하는 데 사용돼요. 빌드 스크립트가 이 경로를 사용해서 레지스트리 JSON 페이로드를 파싱하고, 변환하고, 빌드해요.

type

type 속성은 파일의 유형을 지정하는 데 사용돼요. 자세한 내용은 type 섹션을 참고해요.

target

target 속성은 파일이 프로젝트 어디에 배치되어야 하는지 나타내는 데 사용돼요. 선택 사항이며, registry:page와 registry:file 유형에서만 필수예요.

기본적으로 shadcn CLI는 프로젝트의 components.json 파일을 읽어서 대상 경로를 결정해요. 라우트나 설정 같은 일부 파일은 대상 경로를 직접 지정할 수 있어요.

프로젝트의 루트를 가리키려면 ~를 사용하면 돼요. 예: ~/foo.config.js.

tailwind

tailwind 속성은 theme, plugins, content 같은 tailwind 설정에 사용돼요. tailwind.config 속성을 사용하면 레지스트리 항목에 색상, 애니메이션, 플러그인을 추가할 수 있어요.

{
  "tailwind": {
    "config": {
      "theme": {
        "extend": {
          "colors": {
            "brand": "hsl(var(--brand))"
          },
          "keyframes": {
            "wiggle": {
              "0%, 100%": { "transform": "rotate(-3deg)" },
              "50%": { "transform": "rotate(3deg)" }
            }
          },
          "animation": {
            "wiggle": "wiggle 1s ease-in-out infinite"
          }
        }
      }
    }
  }
}

cssVars

레지스트리 항목의 CSS 변수를 정의할 때 사용해요.

{
  "cssVars": {
    "light": {
      "brand": "20 14.3% 4.1%",
      "radius": "0.5rem"
    },
    "dark": {
      "brand": "20 14.3% 4.1%"
    }
  }
}

**참고:** 색상을 추가할 때는 반드시 `tailwind.config.theme.extend.colors` 속성에도 함께 추가해 주세요.

docs

docs를 사용하면 레지스트리 항목을 CLI로 설치할 때 커스텀 문서나 메시지를 보여줄 수 있어요.

{
  "docs": "Remember to add the FOO_BAR environment variable to your .env file."
}

categories

categories를 사용하면 레지스트리 항목을 분류해서 정리할 수 있어요.

{
  "categories": ["sidebar", "dashboard"]
}

meta

meta를 사용하면 레지스트리 항목에 추가 메타데이터를 넣을 수 있어요. 레지스트리 항목에서 사용하려는 key/value 쌍은 무엇이든 추가할 수 있어요.

{
  "meta": { "foo": "bar" }
}

더 알아보기 (Learn more)

• registry.json 스키마
• JSON Schema: registry-item.json