When you build with Payload CMS and Next.js, reusable blocks are easy to imagine but annoying to distribute cleanly.
A block is rarely just one component file. It usually needs a Payload block config, a frontend renderer, a collection registration, a renderer map entry, regenerated Payload types, and an updated admin import map. Copying the files is the easy part. Remembering the wiring every time is where projects drift.
That is the problem Payload Components is trying to solve.
Payload Components is an MIT registry and CLI for Payload v3 + Next.js blocks. The tagline is:
Install Payload CMS blocks wired, not pasted.
The basic flow looks like this:
npx payload-components add hero-basic
A plain shadcn add copies files into your project. payload-components add copies the block source too, but it also performs the Payload-specific setup: it registers the block in the collection, maps the renderer, regenerates types and the admin import map, records install state, and leaves the result as a normal reviewable git diff.
Why copying files is not enough
Payload blocks touch both editor schema and frontend rendering. If a registry only copies a component file, the install still leaves work behind:
- import the block config
- register the block in the right collection
- import the frontend renderer
- add the renderer to the block map
- regenerate Payload types
- regenerate the admin import map
Those steps are small, but they repeat in every project. They are also easy to get slightly wrong when components evolve.
What the CLI does
The CLI treats each block as source code you own. It builds the registry item, installs files through the shadcn-compatible path, applies the supported Payload wiring, runs the post-install generation steps, and records install state so reruns converge instead of duplicating setup.
The result is deliberately boring: a git diff you can review, edit, and keep.
Current status
The project is open source and MIT licensed. The catalog is intentionally small while the install contract is hardened around Payload v3 + Next.js projects shaped like the official website starter.
Links:
- Site: https://www.payload-components.xyz
- GitHub: https://github.com/Ducksss/payload-components
- Docs: https://www.payload-components.xyz/docs
- Catalog: https://www.payload-components.xyz/components
Feedback from Payload and Next.js teams would be useful, especially around repo shapes the installer should support next and which block families should be added first.