[blocked]
Payload Components
Payload CMS blocks, wired - not pasted.
Payload Components is an MIT, community-first registry and CLI for installing typed Payload CMS blocks into Payload v3 + Next.js projects. It copies the files, wires Payload config, regenerates generated artifacts, and leaves the whole install as a reviewable git diff.
· · · ·
Table of Contents
About The Project
Payload Components installs Payload CMS blocks into supported Payload v3 + Next.js projects.
A plain shadcn add copies files. payload-components add goes further:
- copies component source through the shadcn-compatible registry;
- registers the block in the Pages collection;
- maps the frontend renderer;
- regenerates Payload types and the admin import map;
- records install state so reruns converge instead of duplicating wiring.
This repository has two jobs:
- the Fumadocs-powered Next.js site for the landing page, docs, component catalog, search, Open Graph images, and AI-readable text surfaces;
- the
payload-componentsregistry and CLI that install blocks into consumer Payload projects.
This repository is not a Payload CMS runtime app. The docs site does not need
Payload admin routes, collections, globals, a database adapter, or
PAYLOAD_SECRET.
()
Why It Exists
are not live when their files land. They have to be registered, rendered, typed, and added to the admin import map. That wiring is repetitive, easy to drift, and usually rediscovered project by project.
Payload Components packages the block source and the wiring contract together. The goal is a catalog that grows from real installs and pull requests: MIT, open source, no pricing tiers, no license keys, no gated component access.
()
What Makes This Different
- MIT end to end: registry, CLI, components, and docs site.
- No license keys, gated components, or paid component tiers.
- Community-driven requests and pull requests decide what ships next.
- One command installs source files plus the Payload wiring that makes them live.
()
Built With
()
What Lives Here
()
Getting Started
There are two workflows: installing components into a Payload project, and working on this repository.
Use A Component
Run the CLI from the root of a supported Payload v3 + Next.js project:
Preview the same validation and install plan without changing files, installing dependencies, running generation commands, or updating install state:
The preview lists the component files, RenderBlocks.tsx renderer mapping,
Pages/index.ts block registration, package dependencies, and post-install
commands the real install would use.
To also write a prefilled demo script after the install succeeds, opt in with
--demo, then run the generated TypeScript through your project's Payload CLI:
For a component that is already installed, the standalone command writes the same script:
seed requires a healthy installed-state record, compatible dependencies, every
manifest and registry-dependency file, and all Payload wiring fragments. It
writes the reviewable script plus a private ownership record under
.payload-components/demo-state/. The generated script requires Pages drafts
before querying or changing content, then creates a component-specific draft
Page at /payload-components-demo-hero-basic; it never publishes the demo. A
rerun updates only the exact Page ID recorded locally after verifying its
tokenized block marker. Placeholder media is reused only by its recorded ID and
is never deduplicated or deleted automatically. Before each create, the script
atomically journals a unique operation token; after an interruption it can
adopt only the single Page or Media carrying that exact private token and record
its returned ID before continuing. Any collision or missing,
mismatched, or unreadable ownership record stops before unsafe mutation. The CLI
atomically replaces only its version-marked generated script and refuses unowned
files or pre-existing symlinks. The operator-run script deliberately uses
overrideAccess: true, with overrideLock: false for updates, so review it in
git and run it only against the intended database.
Good first installs:
Browse the full, current set in the .
All components
Every installable registry item, in catalog order. This table and the CLI's
Current components help output are both verified against
payload-components/registry.json by a focused test, so neither can silently
drift from the registry.
Install several blocks in one command — add takes any number of names, and the
catalog's composer builds the command for you as you tick components:
Install every block a full-site template concept composes, then assemble its pages in the admin:
add-template installs and wires the whole block set and prints which blocks
each page uses. Add --demo to also write one seed script per page, each
creating a draft Page from the blocks that page composes. Seeded content is each
block's own sample content, not the curated copy shown on the site.
Mark a block's text fields as localized for Payload localization:
This also installs src/blocks/shared/localizeFields.ts and wraps the block
config's field list in it, so the shared family base is covered too. Enable
localization in your Payload config for it to take effect, and migrate existing
data before adopting it on a populated collection.
Maintain an install
Recorded installs have a full lifecycle, not just a first run:
diff exits non-zero when anything has drifted, so CI can gate on it. update
never overwrites a file you have edited — it skips that component and exits
non-zero until you pass --force. remove deletes only the files no other
installed component ships, so a shared family base survives while a sibling
variant is still installed; package dependencies are always left in place.
list and diff accept --json, and update and remove accept --dry-run.
Starting from a bare create-payload-app project? Lay down the base an install
needs — the Pages and Media collections, the blocks renderer, and the cn /
CMSLink / Media / linkGroup primitives every block imports:
Nothing is overwritten: files you already have are kept, and a re-run creates
nothing. The result is the official starter's shape, so the project then detects
as payload-website-starter.
Check a target project without changing files:
doctor validates the supported project shape, resolves which files carry the
wiring, and checks required post-install scripts and any recorded
.payload-components/state.json installs.
Use it from a coding agent
payload-components mcp runs a Model Context Protocol server over stdio so an
agent can browse the registry, read a component's install contract, and preview
what an install would change:
Every tool is read-only by design. The server answers which block and what will
it change; installing stays an explicit payload-components add run in your
shell, where the diff is visible and approvable.
()
Run This Repo Locally
Use these steps to run the docs site and registry tooling.
Prerequisites:
- Node.js
^20.19.0 || >=22.12.0 - pnpm
^9 || ^10
Install and start:
Open .
Useful local routes:
()
Usage
The installer runs five idempotent stages:
- Build or resolve the public registry item.
- Add component files through the shadcn registry.
- Install required dependencies.
- Apply Payload fragments for collection registration and renderer mapping.
- Run post-install scripts for generated types and the admin import map.
Install state is written to .payload-components/state.json inside the
consumer project, so partial installs are visible and retries can converge.
Demo scripts are separate and opt-in. add <component> --demo writes one only
after those install stages and installed-state recording succeed;
seed <component> rejects recorded partial installs and verifies the installed
state, dependencies, manifest and registry-dependency files, and Payload
fragments again. Its separate private demo-state file records the IDs the
operator-run script may update.
Neither command opens a database. The CLI prints the package-manager-specific
payload run command that performs the database work in your project.
Recovering an interrupted install
If a stage fails, the component is recorded as partial and payload-components add
prints the failed stage, the last error, and the safest retry command. Fix the
reported cause, then rerun the same command from the project root:
Review the git diff before editing anything by hand. The CLI distinguishes two
kinds of files: owned component files (listed from the manifest, such as the
files under src/blocks/HeroBasic/) are safe to re-create by retrying, while
patched host files are project files the installer edited and may hold your own
work — normally src/blocks/RenderBlocks.tsx, src/collections/Pages/index.ts,
package.json, and the package manager lockfile.
Prefer forward fixes over deletion. Do not delete patched host files to recover.
Use payload-components doctor to see the failed stage, missing files, missing
Payload fragments, and the owned/patched file breakdown before and after retrying.
Useful checks while changing this repo:
Run the full local release gate before shipping:
()
Package Releases
Public installs use the npm package:
GitHub releases publish payload-components to npm and mirror
@ducksss/payload-components to GitHub Packages. Prerelease versions publish
under the next dist tag; stable versions publish under latest.
()
Roadmap
Payload Components stays open-source and community-first. The roadmap is about improving the install contract, expanding useful blocks, and making real contribution paths obvious.
Read for the current direction, or use for active work and component requests.
()
Community Examples
Sites and projects built with Payload Components. If you shipped something with
these blocks, add it here: open a into dev
that appends one row to the table.
Nothing listed yet, so the first row is available. Copy this, fill it in, and add it to the end of the table:
Row guidelines:
- Site: a public, working URL, linked from the bare domain.
- Author: your GitHub handle, linked to your profile.
- Tags: a few words on what the site is, or the component families it leans on.
- Source:
[↗](repository-url)when the code is public,-when it is not.
There is no minimum size and one installed block counts. Real installs are the clearest signal about what to build next, so say in the pull request which components you used and what you had to change.
()
Contributing
Contributions are welcome. The useful shape is a complete change: source, manifest, docs, demo twin, and installer coverage together when adding or changing a component.
Looking for a first issue? Both searches list currently open work, so they stay accurate as issues land:
- - small, self-contained tasks that do not assume prior context on the registry or CLI.
- - open work of any size where a contributor would be welcome.
Community docs:
- - setup, branches, tests, and PR shape.
- - how we keep discussion useful.
- - how to report vulnerabilities privately.
- - what is planned, and what is not.
Basic flow:
- Fork the project.
- Create a feature branch from
dev. - Make the change with focused tests.
- Run the relevant checks and note them in the pull request.
- Open a pull request into
dev.
()
License
Distributed under the MIT License. See for more information.
()
Join The Community
- Maintainer:
- Website:
- Issues:
- Security:
- Project Link:
()
Acknowledgments
- for the README structure.
- for the target CMS ecosystem.
- for the registry model Payload Components builds on.
- (MIT) for marketing block layouts adapted into several component families.
- for the documentation site foundation.
- Everyone opening issues, testing installs, and contributing blocks in public.
()