1# Registry Authoring and Addresses
2 
3Use this reference when the user wants to create, fix, publish, or reason about
4a shadcn registry.
5 
6## Mental Model
7 
8A registry has two forms:
9 
10- **Source registry**: an authored `registry.json` in a project or repository.
11  It may use `include` and file paths that point at source files.
12- **Built registry**: generated JSON files served to CLI consumers, usually
13  from `public/r`. Use `npx shadcn@latest build` to create this form.
14 
15The CLI installer consumes registry item payloads. A source registry is a way to
16author those payloads from real files.
17 
18Registry items are not limited to React components. They can distribute
19components, hooks, utilities, design tokens, pages, config files, docs, rules,
20workflows, templates, MCP files, and other project files.
21 
22## Root `registry.json`
23 
24The root registry file should define registry metadata and either `items` or
25`include`.
26 
27```json
28{
29  "$schema": "https://ui.shadcn.com/schema/registry.json",
30  "name": "acme",
31  "homepage": "https://acme.com",
32  "items": [
33    {
34      "name": "absolute-url",
35      "type": "registry:lib",
36      "title": "Absolute URL",
37      "description": "A utility to turn any path into an absolute URL.",
38      "files": [
39        {
40          "path": "lib/absolute-url.ts",
41          "type": "registry:lib"
42        }
43      ]
44    }
45  ]
46}
47```
48 
49Root registry rules:
50 
51- Root `registry.json` must include `name` and `homepage`.
52- `items` is an array of registry item definitions.
53- `include` may be used to split the source registry into multiple files.
54- Included registry files may omit `name` and `homepage`.
55 
56## Include
57 
58Use `include` to keep large registries modular.
59 
60```json
61{
62  "$schema": "https://ui.shadcn.com/schema/registry.json",
63  "name": "acme",
64  "homepage": "https://acme.com",
65  "include": ["registry/ui/registry.json", "registry/blocks/registry.json"]
66}
67```
68 
69Include rules:
70 
71- Include paths are relative to the `registry.json` that declares them.
72- Include paths must explicitly point to a `registry.json` file.
73- Do not use remote URLs, absolute paths, or parent traversal (`..`).
74- Item file paths are relative to the registry file that declares the item.
75- Duplicate item names fail across the resolved registry.
76 
77Example included file:
78 
79```json
80{
81  "items": [
82    {
83      "name": "button",
84      "type": "registry:ui",
85      "files": [
86        {
87          "path": "button.tsx",
88          "type": "registry:ui"
89        }
90      ]
91    }
92  ]
93}
94```
95 
96If this file is at `registry/ui/registry.json`, then `button.tsx` is read from
97`registry/ui/button.tsx`, and the built item path is emitted relative to the
98root registry.
99 
100## Item Definitions
101 
102Common item fields:
103 
104```json
105{
106  "name": "login-form",
107  "type": "registry:block",
108  "title": "Login Form",
109  "description": "A login form with email and password fields.",
110  "dependencies": ["zod"],
111  "registryDependencies": ["button", "input", "label"],
112  "files": [
113    {
114      "path": "blocks/login-form.tsx",
115      "type": "registry:block"
116    }
117  ],
118  "cssVars": {
119    "light": {
120      "brand": "oklch(0.62 0.18 250)"
121    },
122    "dark": {
123      "brand": "oklch(0.72 0.16 250)"
124    }
125  }
126}
127```
128 
129Important fields:
130 
131- `name`: the installable item name. It is not necessarily a file path.
132- `type`: one of the registry item types, such as `registry:ui`,
133  `registry:block`, `registry:lib`, `registry:hook`, `registry:file`,
134  `registry:page`, `registry:theme`, `registry:style`, `registry:font`, or
135  `registry:item`.
136- `files`: source files copied or generated by the item.
137- `dependencies`: npm runtime dependencies.
138- `devDependencies`: npm development dependencies.
139- `registryDependencies`: other registry items required by this item.
140- `cssVars`, `css`, `tailwind`, `envVars`, and `docs`: optional install-time
141  additions.
142 
143File rules:
144 
145- File paths are relative to the declaring `registry.json`.
146- `registry:file` and `registry:page` files require a `target`.
147- Do not use remote file URLs in source registry file paths.
148- Keep source files copy-pasteable: no hidden app-only imports.
149 
150## Registry Dependencies
151 
152`registryDependencies` entries are item addresses, not file paths.
153 
154```json
155{
156  "name": "login-form",
157  "type": "registry:block",
158  "registryDependencies": ["button", "@acme/input", "acme/ui/card#v1.2.0"],
159  "files": [
160    {
161      "path": "blocks/login-form.tsx",
162      "type": "registry:block"
163    }
164  ]
165}
166```
167 
168Dependency rules:
169 
170- Bare names such as `"button"` mean official shadcn items.
171- Bare names never mean same-registry or same-repository items.
172- Namespaced dependencies use `@namespace/item-name`.
173- GitHub dependencies use `owner/repo/item-name`.
174- Pin GitHub dependencies with `owner/repo/item-name#ref` when needed.
175- Refs are not inherited. If `owner/repo/foo#v2` depends on `bar` from the same
176  repo at `v2`, write `owner/repo/bar#v2`.
177- Do not use relative dependencies such as `"./bar"`.
178 
179## Address Schemes
180 
181When reasoning about a registry item string, classify it first.
182 
183| Address                             | Scheme    | Meaning                                                      |
184| ----------------------------------- | --------- | ------------------------------------------------------------ |
185| `button`                            | shadcn    | Official shadcn item named `button`.                         |
186| `@acme/button`                      | namespace | Item `button` from configured registry `@acme`.              |
187| `@acme/ui/button`                   | namespace | Item `ui/button` from configured registry `@acme`.           |
188| `https://example.com/r/button.json` | url       | Built registry item JSON at that URL.                        |
189| `./button.json`                     | file      | Built registry item JSON on disk.                            |
190| `acme/ui/button`                    | github    | Item `button` from GitHub repo `acme/ui`.                    |
191| `acme/ui/forms/login#main`          | github    | Item `forms/login` from GitHub repo `acme/ui` at ref `main`. |
192 
193For namespace and GitHub addresses, slashful item names are allowed and are item
194names, not file paths. Addresses ending in `.json` keep file-address
195precedence, so `acme/ui/data/schema.json` is treated as a file path, not a
196GitHub item address.
197 
198## GitHub Registries
199 
200A public GitHub repository can act as a source registry when it has a root
201`registry.json`.
202 
203```txt
204owner/repo/item-name[#ref]
205```
206 
207Rules:
208 
209- The first two path segments are GitHub owner and repo.
210- All remaining path segments are the registry item name.
211- The source entrypoint is always root `registry.json`.
212- GitHub registries are source registries consumed directly by the CLI. They do
213  not require `shadcn build` or generated item JSON files.
214- `include` follows the same source-registry rules as local registries.
215- Currently, GitHub addresses support public `github.com` repositories only.
216- Private repos and GitHub Enterprise require explicit product decisions.
217 
218When implementing GitHub registry fetching, resolve refs to a commit SHA before
219reading source files. Do not read moving refs directly from
220`raw.githubusercontent.com`, because branch-like refs can be cached for several
221minutes.
222 
223Preferred flow:
224 
225```txt
226owner/repo[#ref]
227  -> resolve ref with git ls-remote
228  -> commit SHA
229  -> read https://raw.githubusercontent.com/{owner}/{repo}/{sha}/registry.json
230  -> read includes and item files from the same SHA
231```
232 
233This keeps a command on one consistent repository snapshot.
234 
235Full 40-character commit SHAs are already stable and can be used directly.
236Branches, tags, and short refs require Git so the CLI can resolve them to a
237commit SHA first.
238 
239## Build and Verify
240 
241Use the CLI to build source registries:
242 
243```bash
244npx shadcn@latest build
245npx shadcn@latest build registry.json --output public/r
246```
247 
248Use CLI commands to inspect the result:
249 
250```bash
251npx shadcn@latest list @acme
252npx shadcn@latest search @acme -q "login"
253npx shadcn@latest view @acme/login-form
254npx shadcn@latest add @acme/login-form --dry-run
255npx shadcn@latest registry validate ./registry.json
256```
257 
258Use GitHub addresses directly for public GitHub registries:
259 
260```bash
261npx shadcn@latest list owner/repo
262npx shadcn@latest search owner/repo -q "login"
263npx shadcn@latest view owner/repo/item
264npx shadcn@latest add owner/repo/item --dry-run
265npx shadcn@latest registry validate owner/repo
266```
267 
268When working on registry implementation in the shadcn/ui codebase:
269 
270- Keep address parsing pure and testable.
271- Do not add side effects to validators.
272- Preserve existing behavior for official shadcn, namespace, URL, and file
273  schemes.
274- Add tests for address parsing, source loading, dependency resolution, list,
275  search, view, and add paths.
276- Prefer small source-reader abstractions over a plugin system until there are
277  multiple real providers.
278