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.",
  "registryDependencies": [
    "button",
    "@acme/input-form",
    "https://example.com/r/foo"
  ],
  "dependencies": ["is-even@3.0.0", "motion"],
  "devDependencies": ["tw-animate-css"],
  "files": [
    {
      "path": "registry/new-york/hello-world/hello-world.tsx",
      "type": "registry:component"
    },
    {
      "path": "registry/new-york/hello-world/use-hello-world.ts",
      "type": "registry:hook"
    }
  ],
  "cssVars": {
    "theme": {
      "font-heading": "Poppins, sans-serif"
    },
    "light": {
      "brand": "oklch(0.205 0.015 18)"
    },
    "dark": {
      "brand": "oklch(0.205 0.015 18)"
    }
  }
}

その他の例を見る

定義

registry-item.json の JSON スキーマはこちらで確認できます。

$schema

$schema プロパティは、registry-item.json ファイルのスキーマを指定するために使用します。

registry-item.json

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

name

アイテムの名前です。レジストリ内でアイテムを識別するために使用します。レジストリ内で一意である必要があります。

registry-item.json

{
  "name": "hello-world"
}

title

レジストリアイテムの人間が読みやすいタイトルです。短く分かりやすくしてください。

registry-item.json

{
  "title": "Hello World"
}

description

レジストリアイテムの説明です。title よりも長く、詳しく記述できます。

registry-item.json

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

type

type プロパティは、レジストリアイテムの種類を指定するために使用します。プロジェクト向けにアイテムを解決する際の種類や配置先パスの決定に使用されます。

registry-item.json

{
  "type": "registry:block"
}

以下の種類がサポートされています：

Type	Description
`registry:base`	デザインシステム全体に使用します。
`registry:block`	複数ファイルで構成される複雑なコンポーネントに使用します。
`registry:component`	シンプルなコンポーネントに使用します。
`registry:font`	フォントに使用します。
`registry:lib`	ライブラリやユーティリティに使用します。
`registry:hook`	フックに使用します。
`registry:ui`	UI コンポーネントや単一ファイルのプリミティブに使用します。
`registry:page`	ページやファイルベースのルートに使用します。
`registry:file`	その他のファイルに使用します。
`registry:style`	レジストリスタイルに使用します。例：`new-york`。
`registry:theme`	テーマに使用します。
`registry:item`	汎用レジストリアイテムに使用します。

author

author プロパティは、レジストリアイテムの作成者を指定するために使用します。

レジストリアイテム固有の作成者にも、レジストリの作成者と同じ値にもできます。

registry-item.json

{
  "author": "John Doe <john@doe.com>"
}

dependencies

dependencies プロパティは、レジストリアイテムの依存関係を指定するために使用します。npm パッケージ用です。

パッケージのバージョンを指定する場合は @version を使用します。

registry-item.json

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

devDependencies

devDependencies プロパティは、レジストリアイテムの開発用依存関係を指定するために使用します。開発時のみ必要となる npm パッケージ用です。

パッケージのバージョンを指定する場合は @version を使用します。

registry-item.json

{
  "devDependencies": ["tw-animate-css", "name@1.2.0"]
}

registryDependencies

レジストリの依存関係に使用します。各エントリはアイテムのアドレスです。

button、input、select などの shadcn/ui レジストリアイテムの場合は、名前を使用します（例：['button', 'input', 'select']）。
名前空間付きレジストリアイテムの場合は、@namespace/item-name を使用します（例：['@acme/input-form']）。
GitHub レジストリアイテムの場合は、owner/repo/item-name を使用します（例：['acme/ui/button']）。公開レジストリでは、タグまたは完全なコミット SHA の使用を推奨します（例：['acme/ui/button#v1.2.0']）。
カスタムレジストリアイテムの場合は、レジストリアイテムの URL を使用します（例：['https://example.com/r/hello-world.json']）。
ローカルのレジストリアイテムファイルの場合は、ファイルパスを使用します（例：['./hello-world.json']）。

registry-item.json

{
  "registryDependencies": [
    "button",
    "@acme/input-form",
    "acme/ui/button#v1.2.0",
    "https://example.com/r/editor.json",
    "./editor.json"
  ]
}

注意：ベアネームは従来の動作を維持します。button は、同じ GitHub リポジトリ内のアイテムではなく、組み込みの shadcn の button アイテムを指します。同じリポジトリ内の GitHub 依存関係には、完全な GitHub アイテムアドレスを使用してください。

参照は依存関係間で継承されません。GitHub の依存関係を再現可能にする場合は、その依存関係自体をタグまたは完全なコミット SHA に固定してください。

詳しくは GitHub レジストリのドキュメントをご覧ください。

files

files プロパティは、レジストリアイテムのファイルを指定するために使用します。各ファイルは path、type、target（任意）プロパティを持ちます。

target プロパティは、registry:page および registry:file タイプでは必須です。

registry-item.json

{
  "files": [
    {
      "path": "registry/new-york/hello-world/page.tsx",
      "type": "registry:page",
      "target": "app/hello/page.tsx"
    },
    {
      "path": "registry/new-york/hello-world/hello-world.tsx",
      "type": "registry:component"
    },
    {
      "path": "registry/new-york/hello-world/use-hello-world.ts",
      "type": "registry:hook"
    },
    {
      "path": "registry/new-york/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）。

レジストリターゲットプレースホルダーを使用すると、ユーザーの components.json で設定されたディレクトリ配下にファイルを配置することもできます。これらのプレースホルダーは target の先頭でのみサポートされ、プロジェクトのインポートプレフィックスとは無関係です。たとえば、@ui/button.tsx は、プロジェクトがコンポーネントを @/、#、パッケージインポート、ワークスペースエクスポートのいずれでインポートしている場合でも動作します。

Placeholder	Resolves to
`@components/`	`aliases.components`
`@ui/`	`aliases.ui`
`@lib/`	`aliases.lib`
`@hooks/`	`aliases.hooks`

これらのプレースホルダーは、components、src、ワークスペースパッケージパスをハードコードせずに、プロジェクトで設定された shadcn ディレクトリにレジストリアイテムをインストールしたい場合に使用します。プレースホルダー以降の部分は保持されるため、@ui/ai/prompt-input.tsx はユーザーが設定した ui ディレクトリ配下の ai/prompt-input.tsx にインストールされます。

registry-item.json

{
  "files": [
    {
      "path": "registry/new-york/example/button.tsx",
      "type": "registry:ui",
      "target": "@ui/button.tsx"
    },
    {
      "path": "registry/new-york/example/prompt-input.tsx",
      "type": "registry:ui",
      "target": "@ui/ai/prompt-input.tsx"
    },
    {
      "path": "registry/new-york/example/card.tsx",
      "type": "registry:component",
      "target": "@components/card.tsx"
    },
    {
      "path": "registry/new-york/example/helper.ts",
      "type": "registry:lib",
      "target": "@lib/helper.ts"
    },
    {
      "path": "registry/new-york/example/use-demo.ts",
      "type": "registry:hook",
      "target": "@hooks/use-demo.ts"
    }
  ]
}

target プロパティは、ファイルの書き込み先を決定します。ファイルの type とは異なる shadcn ディレクトリを指定することもできます。

registry-item.json

{
  "files": [
    {
      "path": "registry/new-york/example/format-date.ts",
      "type": "registry:ui",
      "target": "@lib/format-date.ts"
    }
  ]
}

不明なプレースホルダーは通常のターゲットパスとして扱われます。たとえば、@foo/bar.ts は foo/bar.ts として書き込まれます。components/@ui/button.tsx のような途中に埋め込まれたプレースホルダーも通常のパスとして扱われます。

@utils/ はサポートされていません。utils はディレクトリではなくファイルを指すためです。

tailwind

非推奨： Tailwind v4 プロジェクトでは、代わりに cssVars.theme を使用してください。

tailwind プロパティは、theme、plugins、content などの Tailwind 設定に使用します。

tailwind.config プロパティを使用して、レジストリアイテムにカラー、アニメーション、プラグインを追加できます。

registry-item.json

{
  "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 変数を定義するために使用します。

registry-item.json

{
  "cssVars": {
    "theme": {
      "font-heading": "Poppins, sans-serif"
    },
    "light": {
      "brand": "20 14.3% 4.1%",
      "radius": "0.5rem"
    },
    "dark": {
      "brand": "20 14.3% 4.1%"
    }
  }
}

css

プロジェクトの CSS ファイルに新しいルールを追加する場合は css を使用します（例：@layer base、@layer components、@utility、@keyframes、@plugin など）。

registry-item.json

{
  "css": {
    "@plugin @tailwindcss/typography": {},
    "@plugin foo": {},
    "@layer base": {
      "body": {
        "font-size": "var(--text-base)",
        "line-height": "1.5"
      }
    },
    "@layer components": {
      "button": {
        "background-color": "var(--color-primary)",
        "color": "var(--color-white)"
      }
    },
    "@utility text-magic": {
      "font-size": "var(--text-base)",
      "line-height": "1.5"
    },
    "@keyframes wiggle": {
      "0%, 100%": {
        "transform": "rotate(-3deg)"
      },
      "50%": {
        "transform": "rotate(3deg)"
      }
    }
  }
}

envVars

レジストリアイテムに環境変数を追加する場合は envVars を使用します。

registry-item.json

{
  "envVars": {
    "NEXT_PUBLIC_APP_URL": "http://localhost:4000",
    "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/postgres",
    "OPENAI_API_KEY": ""
  }
}

環境変数は .env.local または .env ファイルに追加されます。既存の変数は上書きされません。

重要： envVars は開発用またはサンプル用の変数の追加に使用してください。本番用の変数には使用しないでください。

font

font プロパティは registry:font アイテムで必須です。フォントファミリー、プロバイダー、インポート名、CSS 変数、および Next.js 以外のプロジェクト用にインストールする npm パッケージを設定します。

registry-item.json

{
  "font": {
    "family": "'Inter Variable', sans-serif",
    "provider": "google",
    "import": "Inter",
    "variable": "--font-sans",
    "subsets": ["latin"],
    "dependency": "@fontsource-variable/inter"
  }
}

Property	Type	Required	Description
`family`	`string`	Yes	CSS の font-family の値です。
`provider`	`string`	Yes	フォントプロバイダーです。現在は `google` のみサポートされています。
`import`	`string`	Yes	`next/font/google` からフォントをインポートする際のインポート名です。
`variable`	`string`	Yes	フォント用の CSS 変数名です（例：`--font-sans`、`--font-mono`）。
`weight`	`string[]`	No	含めるフォントウェイトの配列です。
`subsets`	`string[]`	No	含めるフォントサブセットの配列です。
`selector`	`string`	No	フォントを適用する CSS セレクターです。既定値は `html` です。
`dependency`	`string`	No	Next.js 以外のプロジェクト用にインストールする npm パッケージです（例：`@fontsource-variable/inter`）。

docs

CLI でレジストリアイテムをインストールする際にカスタムドキュメントやメッセージを表示する場合は docs を使用します。

registry-item.json

{
  "docs": "To get an OPENAI_API_KEY, sign up for an account at https://platform.openai.com."
}

registry-item.json

定義

$schema

name

title

description

type

author

dependencies

devDependencies

registryDependencies

files

path

type

target

tailwind

cssVars

css

envVars

font

docs

categories

meta