Registry Contract
How the public registry, manifests, and wrapper CLI work together.
Payload Components delivers a component in two layers — a shadcn registry that moves files, and a manifest that captures the Payload-specific wiring the registry can't express.
Public registry
A shadcn-compatible JSON registry that delivers a component's source files into the target project.
Wrapper manifest
The Payload-specific contract: fragments, post-install scripts, peer deps, and recovery metadata the CLI applies on top.
Public registry
The public registry is generated from payload-components/registry.json:
pnpm registry:buildThe generated files are emitted to public/r and can be served statically.
public/r is build output — gitignored and reproducible. Never hand-edit it;
edit payload-components/registry.json and rebuild.
Namespace installs
Because the generated registry is shadcn-compatible, consumers can install blocks with the plain shadcn CLI by registering the namespace in their components.json:
{
"registries": {
"@payload-components": "https://www.payload-components.xyz/r/{name}.json"
}
}pnpm dlx shadcn@latest add @payload-components/hero-basicA namespaced shadcn add delivers files and shadcn UI dependencies only — the
Payload wiring lives in the manifests and is applied by
payload-components add. See Installation
for the full comparison.
Manifests
Each wrapper manifest in payload-components/manifests defines:
- supported Payload and Next.js majors
- files expected after install
- peer dependency requirements
- Payload fragments to apply
- post-install scripts
- recovery metadata for patched files
- sample content for docs and testing
Support matrix
payload-components/support-matrix.json defines the target project shapes the installer understands.
The current support matrix is intentionally narrow. New project shapes should be added only when the installer can verify them with tests.
Recovery state
The CLI records install state in .payload-components/state.json inside the target project.
That state is not a substitute for disk verification — the installer still checks actual files and fragments before declaring a component installed.