A public registry is executable distribution input. People use its JSON to write files and install dependencies in their repositories. “It worked on the maintainer's laptop” is not enough. The same source and lockfile should produce the same resolved items from a clean checkout, and every item should pass schema and path validation before deployment.
Payload Components treats payload-components/registry.json and component source as canonical.
public/r is generated output. Reproducibility proves those inputs fully describe what the site will
serve.
Keep one source of truth
Edit the source registry and files under payload-components/source. Never patch generated public
JSON by hand. The next build would erase the change, and the repository would no longer explain its
deployed output.
Each file entry has two paths: the repository source and consumer target. Source paths may be reorganized internally. Targets are part of the public installation contract and require matching updates to imports, manifests, docs, and tests.
The shadcn registry article describes item fields and direct delivery. The current upstream registry item specification remains the primary schema reference.
Pin the build environment
Use the package lockfile, a supported Node version, and the repository's package-manager command. Unpinned generators can change ordering, defaults, formatting, or schema interpretation without a source diff.
The build script invokes shadcn build against the explicit source registry and output directory.
Avoid timestamps, absolute machine paths, random IDs, and network-fetched content in generated items.
Resolved file content should come from the checkout.
If upstream tooling changes intended output, update the dependency and generated expectations in one reviewed change. Reproducibility is version-relative, not a claim that output never evolves.
Validate schema locally
This repository vendors the relevant shadcn schemas and validates every source item in the release gate. Local validation is faster and more deterministic than discovering a malformed item after deployment or relying only on a directory's remote checker.
Schema validation catches missing names, invalid item types, malformed dependency fields, and file entries that do not match the format. Project-specific checks add requirements the public schema does not know, such as allowed target roots and agreement with Payload manifests.
Vendored schemas need deliberate updates when the upstream specification changes. Record the source and version so validation has provenance rather than becoming a mysterious frozen copy.
Enforce target-path safety
Registry installation writes to another repository. Validate normalized targets and reject absolute paths, traversal segments, unexpected roots, or names that change URL resolution. Component names and public item URLs also need constrained construction.
Source paths should remain inside the intended registry source directory. Symlinks and path normalization deserve attention in tooling that reads file content. The safe default is a narrow allowlist of repository and consumer roots.
These checks are not merely quality rules. They are part of the security boundary for a distribution format that performs filesystem writes.
Compare output from a clean build
pnpm registry:check creates one temporary build from the canonical registry and component source. It
parses that output and performs three comparisons: registry-index metadata, each item's metadata, and
the exact embedded content of every declared source file.
Schema validation is a separate gate. pnpm registry:validate verifies source items against the
vendored schemas and project path rules, while registry:check proves the generated index and items
still resolve exactly from repository inputs. The aggregate pnpm test:registry runs registry:check
and registry:validate. Keeping those jobs distinct makes a failure specific: malformed source and
unexpected generated content do not collapse into one vague result.
Sort only where the format treats order as irrelevant. Do not normalize away meaningful differences. Exact embedded-content comparison is easiest to reason about when the generator is deterministic.
Test installation, not only JSON
A schema-valid registry can still ship an import whose sibling file is missing. Install representative items into temporary fixtures and inspect their target files. Typecheck target source through the source build. For Payload-required items, run the companion installer tests so manifest fragments and registry files agree.
Shared family modules need isolation tests: install one variant without siblings and confirm every relative import resolves. The complete contribution guide lists the surfaces a new component must update together.
Re-run installation to check idempotency. Reproducible delivery and idempotent integration are separate properties; a dependable release needs both.
Verify the live deployment
After changes merge and deploy, request the public index and representative item URLs. Confirm a successful response, JSON content type, embedded source, and the same target paths validated locally. Only then submit or update the registry in an external directory.
External directory requirements can change. At submission time, verify current logo, description, URL, and ordering rules in the upstream repository rather than relying on an old example. Their validation complements local item-schema checks; it does not replace them.
The registry documentation keeps the project's live URL and direct install contract discoverable.
Make failures useful to contributors
A registry check should name the item, field or path, expected rule, and source file. Avoid dumping a large schema error without the component context. When output differs, show the generated file and a focused diff.
That feedback turns a release gate into a development tool. A contributor can fix one target or missing shared file without understanding the entire build system.
Try a direct item through the supported workflow:
npx payload-components add hero-basicThen run the registry checks and inspect the temporary item locally. If its metadata or embedded content differs from the canonical inputs, capture tool versions and the smallest differing file and open an issue through the contributing guide. Deterministic evidence is exactly what lets an open registry fix the real source instead of normalizing away a symptom.
