zhenyi
d7c4bc7c8e
- Add allow_forking, allow_merge_commit, allow_rebase_merge, allow_squash_merge fields to repo schemas - Add delete_branch_on_merge field to repository models and schemas - Add has_issues, has_pull_requests, has_wiki, homepage fields to repo schemas - Add topics array field to repository schemas and models - Add restore_token_expires_at and restore_token_hash fields to user schemas - Remove UserAvatarResponse and UploadUserAvatarParams schemas completely - Update CreateRepoParams and UpdateRepoParams with new repository settings - Modify CreateTemplateParams and UpdateTemplateParams with notification template fields - Remove description from SetBranchProtectionParams schema - Delete App.css and auth.css files completely - Update App.tsx with routing migration notes
278 lines
8.6 KiB
Markdown
278 lines
8.6 KiB
Markdown
# Registry Authoring and Addresses
|
|
|
|
Use this reference when the user wants to create, fix, publish, or reason about
|
|
a shadcn registry.
|
|
|
|
## Mental Model
|
|
|
|
A registry has two forms:
|
|
|
|
- **Source registry**: an authored `registry.json` in a project or repository.
|
|
It may use `include` and file paths that point at source files.
|
|
- **Built registry**: generated JSON files served to CLI consumers, usually
|
|
from `public/r`. Use `npx shadcn@latest build` to create this form.
|
|
|
|
The CLI installer consumes registry item payloads. A source registry is a way to
|
|
author those payloads from real files.
|
|
|
|
Registry items are not limited to React components. They can distribute
|
|
components, hooks, utilities, design tokens, pages, config files, docs, rules,
|
|
workflows, templates, MCP files, and other project files.
|
|
|
|
## Root `registry.json`
|
|
|
|
The root registry file should define registry metadata and either `items` or
|
|
`include`.
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://ui.shadcn.com/schema/registry.json",
|
|
"name": "acme",
|
|
"homepage": "https://acme.com",
|
|
"items": [
|
|
{
|
|
"name": "absolute-url",
|
|
"type": "registry:lib",
|
|
"title": "Absolute URL",
|
|
"description": "A utility to turn any path into an absolute URL.",
|
|
"files": [
|
|
{
|
|
"path": "lib/absolute-url.ts",
|
|
"type": "registry:lib"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Root registry rules:
|
|
|
|
- Root `registry.json` must include `name` and `homepage`.
|
|
- `items` is an array of registry item definitions.
|
|
- `include` may be used to split the source registry into multiple files.
|
|
- Included registry files may omit `name` and `homepage`.
|
|
|
|
## Include
|
|
|
|
Use `include` to keep large registries modular.
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://ui.shadcn.com/schema/registry.json",
|
|
"name": "acme",
|
|
"homepage": "https://acme.com",
|
|
"include": ["registry/ui/registry.json", "registry/blocks/registry.json"]
|
|
}
|
|
```
|
|
|
|
Include rules:
|
|
|
|
- Include paths are relative to the `registry.json` that declares them.
|
|
- Include paths must explicitly point to a `registry.json` file.
|
|
- Do not use remote URLs, absolute paths, or parent traversal (`..`).
|
|
- Item file paths are relative to the registry file that declares the item.
|
|
- Duplicate item names fail across the resolved registry.
|
|
|
|
Example included file:
|
|
|
|
```json
|
|
{
|
|
"items": [
|
|
{
|
|
"name": "button",
|
|
"type": "registry:ui",
|
|
"files": [
|
|
{
|
|
"path": "button.tsx",
|
|
"type": "registry:ui"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
If this file is at `registry/ui/registry.json`, then `button.tsx` is read from
|
|
`registry/ui/button.tsx`, and the built item path is emitted relative to the
|
|
root registry.
|
|
|
|
## Item Definitions
|
|
|
|
Common item fields:
|
|
|
|
```json
|
|
{
|
|
"name": "login-form",
|
|
"type": "registry:block",
|
|
"title": "Login Form",
|
|
"description": "A login form with email and password fields.",
|
|
"dependencies": ["zod"],
|
|
"registryDependencies": ["button", "input", "label"],
|
|
"files": [
|
|
{
|
|
"path": "blocks/login-form.tsx",
|
|
"type": "registry:block"
|
|
}
|
|
],
|
|
"cssVars": {
|
|
"light": {
|
|
"brand": "oklch(0.62 0.18 250)"
|
|
},
|
|
"dark": {
|
|
"brand": "oklch(0.72 0.16 250)"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Important fields:
|
|
|
|
- `name`: the installable item name. It is not necessarily a file path.
|
|
- `type`: one of the registry item types, such as `registry:ui`,
|
|
`registry:block`, `registry:lib`, `registry:hook`, `registry:file`,
|
|
`registry:page`, `registry:theme`, `registry:style`, `registry:font`, or
|
|
`registry:item`.
|
|
- `files`: source files copied or generated by the item.
|
|
- `dependencies`: npm runtime dependencies.
|
|
- `devDependencies`: npm development dependencies.
|
|
- `registryDependencies`: other registry items required by this item.
|
|
- `cssVars`, `css`, `tailwind`, `envVars`, and `docs`: optional install-time
|
|
additions.
|
|
|
|
File rules:
|
|
|
|
- File paths are relative to the declaring `registry.json`.
|
|
- `registry:file` and `registry:page` files require a `target`.
|
|
- Do not use remote file URLs in source registry file paths.
|
|
- Keep source files copy-pasteable: no hidden app-only imports.
|
|
|
|
## Registry Dependencies
|
|
|
|
`registryDependencies` entries are item addresses, not file paths.
|
|
|
|
```json
|
|
{
|
|
"name": "login-form",
|
|
"type": "registry:block",
|
|
"registryDependencies": ["button", "@acme/input", "acme/ui/card#v1.2.0"],
|
|
"files": [
|
|
{
|
|
"path": "blocks/login-form.tsx",
|
|
"type": "registry:block"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Dependency rules:
|
|
|
|
- Bare names such as `"button"` mean official shadcn items.
|
|
- Bare names never mean same-registry or same-repository items.
|
|
- Namespaced dependencies use `@namespace/item-name`.
|
|
- GitHub dependencies use `owner/repo/item-name`.
|
|
- Pin GitHub dependencies with `owner/repo/item-name#ref` when needed.
|
|
- Refs are not inherited. If `owner/repo/foo#v2` depends on `bar` from the same
|
|
repo at `v2`, write `owner/repo/bar#v2`.
|
|
- Do not use relative dependencies such as `"./bar"`.
|
|
|
|
## Address Schemes
|
|
|
|
When reasoning about a registry item string, classify it first.
|
|
|
|
| Address | Scheme | Meaning |
|
|
| ----------------------------------- | --------- | ------------------------------------------------------------ |
|
|
| `button` | shadcn | Official shadcn item named `button`. |
|
|
| `@acme/button` | namespace | Item `button` from configured registry `@acme`. |
|
|
| `@acme/ui/button` | namespace | Item `ui/button` from configured registry `@acme`. |
|
|
| `https://example.com/r/button.json` | url | Built registry item JSON at that URL. |
|
|
| `./button.json` | file | Built registry item JSON on disk. |
|
|
| `acme/ui/button` | github | Item `button` from GitHub repo `acme/ui`. |
|
|
| `acme/ui/forms/login#main` | github | Item `forms/login` from GitHub repo `acme/ui` at ref `main`. |
|
|
|
|
For namespace and GitHub addresses, slashful item names are allowed and are item
|
|
names, not file paths. Addresses ending in `.json` keep file-address
|
|
precedence, so `acme/ui/data/schema.json` is treated as a file path, not a
|
|
GitHub item address.
|
|
|
|
## GitHub Registries
|
|
|
|
A public GitHub repository can act as a source registry when it has a root
|
|
`registry.json`.
|
|
|
|
```txt
|
|
owner/repo/item-name[#ref]
|
|
```
|
|
|
|
Rules:
|
|
|
|
- The first two path segments are GitHub owner and repo.
|
|
- All remaining path segments are the registry item name.
|
|
- The source entrypoint is always root `registry.json`.
|
|
- GitHub registries are source registries consumed directly by the CLI. They do
|
|
not require `shadcn build` or generated item JSON files.
|
|
- `include` follows the same source-registry rules as local registries.
|
|
- Currently, GitHub addresses support public `github.com` repositories only.
|
|
- Private repos and GitHub Enterprise require explicit product decisions.
|
|
|
|
When implementing GitHub registry fetching, resolve refs to a commit SHA before
|
|
reading source files. Do not read moving refs directly from
|
|
`raw.githubusercontent.com`, because branch-like refs can be cached for several
|
|
minutes.
|
|
|
|
Preferred flow:
|
|
|
|
```txt
|
|
owner/repo[#ref]
|
|
-> resolve ref with git ls-remote
|
|
-> commit SHA
|
|
-> read https://raw.githubusercontent.com/{owner}/{repo}/{sha}/registry.json
|
|
-> read includes and item files from the same SHA
|
|
```
|
|
|
|
This keeps a command on one consistent repository snapshot.
|
|
|
|
Full 40-character commit SHAs are already stable and can be used directly.
|
|
Branches, tags, and short refs require Git so the CLI can resolve them to a
|
|
commit SHA first.
|
|
|
|
## Build and Verify
|
|
|
|
Use the CLI to build source registries:
|
|
|
|
```bash
|
|
npx shadcn@latest build
|
|
npx shadcn@latest build registry.json --output public/r
|
|
```
|
|
|
|
Use CLI commands to inspect the result:
|
|
|
|
```bash
|
|
npx shadcn@latest list @acme
|
|
npx shadcn@latest search @acme -q "login"
|
|
npx shadcn@latest view @acme/login-form
|
|
npx shadcn@latest add @acme/login-form --dry-run
|
|
npx shadcn@latest registry validate ./registry.json
|
|
```
|
|
|
|
Use GitHub addresses directly for public GitHub registries:
|
|
|
|
```bash
|
|
npx shadcn@latest list owner/repo
|
|
npx shadcn@latest search owner/repo -q "login"
|
|
npx shadcn@latest view owner/repo/item
|
|
npx shadcn@latest add owner/repo/item --dry-run
|
|
npx shadcn@latest registry validate owner/repo
|
|
```
|
|
|
|
When working on registry implementation in the shadcn/ui codebase:
|
|
|
|
- Keep address parsing pure and testable.
|
|
- Do not add side effects to validators.
|
|
- Preserve existing behavior for official shadcn, namespace, URL, and file
|
|
schemes.
|
|
- Add tests for address parsing, source loading, dependency resolution, list,
|
|
search, view, and add paths.
|
|
- Prefer small source-reader abstractions over a plugin system until there are
|
|
multiple real providers.
|