Validate and list a shadcn registry

Know what each check proves

A schema-valid source registry can still fail after deployment. A successfully built catalog can still reference a missing item endpoint. A valid item can still fail in a real project because its dependencies or target paths are incomplete.

Treat validation as a sequence: source schema, build output, public discovery, item resolution, and finally an installation plan in a representative consumer project.

1. Validate the source registry

Run the CLI validator from the source registry’s project directory. It resolves includes and validates the registry files and items it finds.

npx shadcn@latest registry validate ./registry.json

The tested fixture reported:

Registry is valid.
- registry.json
- components/ui/registry.json
Checked 2 registry files and 1 item.

Stop here if the validator reports missing files, duplicate item names, unsupported include paths, or schema errors. Do not attempt to paper over those failures in the hosted output.

2. Inspect the built catalog

npx shadcn@latest build registry.json --output public/r

Check the generated files as a distribution artifact:

• public/r/registry.json exists and has a flat items array rather than include.
• Every catalog item has a sibling item JSON endpoint.
• Catalog file entries describe paths and types but do not embed a content property.
• Each sibling item JSON contains the file content the installer needs.

3. Verify the deployed endpoints

Test the deployed origin, not only localhost. Use a representative item and check status, content type, redirects, and the final response body.

curl --fail --location https://example.com/r/registry.json
curl --fail --location https://example.com/r/hello-card.json
npx shadcn@latest view https://example.com/r/hello-card.json

A login page, branded 404 page, HTML error response, or redirect to a homepage is not a usable item endpoint even if its final HTTP status is 200.

4. Check catalog discoverability

The CLI can consume the catalog URL directly. Listing proves the catalog can be read; searching checks that human-facing names and descriptions make the item findable.

npx shadcn@latest list https://example.com/r/registry.json
npx shadcn@latest search https://example.com/r/registry.json -q "hello"

In the tested fixture, both commands returned the single hello-card item. Use stable, unique item names and meaningful descriptions; a technically valid catalog that users cannot understand is not ready for a public directory.

5. Dry-run installation in a real project

Run the final item URL against a disposable or representative project that already has a valid components.json. The dry run resolves dependencies and target paths without writing the planned files.

npx shadcn@latest add https://example.com/r/hello-card.json \
  --cwd ./fixture-app \
  --dry-run

The tested fixture planned one new file and exited successfully:

Files (1) +1 new
+ src/components/ui/hello-card.tsx  create
1 file

Repeat this for items with registry dependencies, package dependencies, CSS variables, custom targets, or framework-specific files. One simple item cannot validate every branch of a complex registry.

6. Prepare the official directory pull request

The official directory is for named namespaces such as @acme. A public GitHub source registry can already be used through an owner/repo/item address and does not need directory submission for that workflow.

As of the review date, a directory candidate must be:

• open source and publicly accessible;
• valid against the registry schema;
• published as a flat catalog with sibling item JSON files; and
• free of embedded file content in the catalog’s file entries.

Fork the shadcn/ui repository, add the registry record to apps/v4/registry/directory.json, run the upstream validator, and open a pull request:

pnpm validate:registries

Expect maintainer review after automated validation. Passing the command does not guarantee acceptance and should not be presented to users as an official endorsement.

Troubleshooting by failure stage

Submission-readiness checklist

• □Source validation succeeds on a clean checkout.
• □The build produces a flat catalog and every sibling item payload.
• □Public endpoints return JSON without authentication or HTML fallbacks.
• □List, search, and view work against the deployed URLs.
• □Representative items produce correct dry-run installation plans.
• □The project is open source and its homepage explains ownership and support.
• □The proposed namespace and URL template match the deployed files.
• □The upstream directory validator passes before opening the pull request.