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.
Installed source and migrations
payload-components add does not overwrite installed component source. A published registry
change therefore affects new installs only; an existing app changes only when its maintainer
deliberately ports the source diff. This preserves local edits and keeps repeat installs
idempotent.
If an adopted source diff adds or changes a persisted identifier such as dbName, the
SQL-backed consumer project must own the migration. After porting the source diff, run
pnpm payload migrate:create <migration-name> in that app. Review the generated DDL to ensure
it will rename rather than drop and recreate the existing tables, indexes, or enums; replace
destructive DDL with an explicit rename or backfill. Test against a backup or staging database,
then run the migration before deploying the updated config. The registry cannot safely generate
a universal migration without the consumer's collection slug, block-field path, adapter, schema,
existing identifiers, and migration history.
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
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.