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:build

The 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-basic

A 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

Article template components such as Post Hero and Author Card declare installMode: 'file-only'. Their registry items use registry:component; fragments, post-install scripts, and recovery paths must all be empty. Other manifests keep the page-block requirements. Direct shadcn installation delivers these standalone React files; the wrapper additionally tracks them for list, diff, update, and remove in a supported Payload project. Neither route changes your Pages collection or renderer. Compose the component in your article template and supply public content as props.

Data-driven blocks may also declare requires.projectFiles. Exact anchors must occur in active source, not comments or string fixtures. A collectionIdentifiers requirement checks that the named collections are direct entries in buildConfig({ collections: [...] }). Computed lists and later config overrides cannot be verified and are refused with recovery guidance. Collection Query requires both Posts and Categories and their config registration.

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.