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.

Explore the docs · Browse the catalog · Contribute · Report a bug · Request a component

Table of Contents

1. About The Project
   • Why It Exists
   • What Makes This Different
   • Built With
   • What Lives Here
2. Getting Started
   • Use A Component
   • Run This Repo Locally
3. Usage
4. Package Releases
5. Roadmap
6. Contributing
7. License
8. Join The Community
9. Acknowledgments

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-components registry 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.

(back to top)

Why It Exists

Payload blocks 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.

(back to top)

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.

(back to top)

Built With

• Next.js
• React
• Fumadocs
• Payload CMS
• shadcn Registry
• TypeScript
• Tailwind CSS
• Playwright
• Vitest

(back to top)

What Lives Here

Path	Purpose
src/app	Next.js routes, homepage, catalog, docs, search, and OG
src/components/site	Site UI, landing sections, install replay, cards, and demos
src/lib/site.ts	Shared site copy, component entries, FAQ, and demo data
content/docs	Fumadocs MDX documentation
payload-components/registry.json	Source shadcn registry definition
payload-components/source	Payload target source files shipped into consumer repos
payload-components/manifests	Install metadata, fragments, post-install tasks, recovery
tools/payload-components	CLI implementation for payload-components add
bin/payload-components.mjs	CLI executable entrypoint
tests	Playwright E2E and Vitest integration coverage

(back to top)

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:

npx payload-components add hero-basic

Good first installs:

Component	Use it for
hero-basic	A headline-led page hero
feature-grid-basic	A repeatable feature grid
feature-split	A two-column feature section
content-columns	Editorial content columns
logo-cloud-grid	A trust-logo wall
integration-grid	Integration cards

Browse the full, current set in the component catalog.

Check a target project without changing files:

npx payload-components doctor

doctor validates the supported project shape, required post-install scripts, and any recorded .payload-components/state.json installs.

(back to top)

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:

git clone https://github.com/Ducksss/payload-components.git
cd payload-components
pnpm install --frozen-lockfile --ignore-workspace
pnpm source:build
pnpm dev

Open http://localhost:3000.

Useful local routes:

Route	Purpose
/	Product and docs homepage
/docs	Fumadocs documentation
/components	Component catalog
/api/search	Fumadocs search endpoint
/llms.txt, /llms-full.txt	AI-readable project summaries
/r/registry.json	Generated public registry

(back to top)

Usage

The installer runs five idempotent stages:

1. Build or resolve the public registry item.
2. Add component files through the shadcn registry.
3. Install required dependencies.
4. Apply Payload fragments for collection registration and renderer mapping.
5. 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.

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:

npx payload-components add hero-basic
npx payload-components doctor

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:

pnpm lint
pnpm source:build
pnpm exec tsc --noEmit
pnpm test:registry
pnpm run test:int
E2E_PORT=3100 pnpm run test:e2e
pnpm build

Run the full local release gate before broad changes:

pnpm test:release

(back to top)

Package Releases

Public installs use the npm package:

npx payload-components add hero-basic

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.

(back to top)

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 ROADMAP.md for the current direction, or use open issues for active work and component requests.

(back to top)

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.

Community docs:

• CONTRIBUTING.md - setup, branches, tests, and PR shape.
• CODE_OF_CONDUCT.md - how we keep discussion useful.
• SECURITY.md - how to report vulnerabilities privately.
• ROADMAP.md - what is planned, and what is not.

Basic flow:

1. Fork the project.
2. Create a feature branch from dev.
3. Make the change with focused tests.
4. Run the relevant checks and note them in the pull request.
5. Open a pull request into dev.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Join The Community

• Maintainer: Ducksss
• Website: payload-components.xyz
• Issues: github.com/Ducksss/payload-components/issues
• Security: GitHub Security Advisories
• Project Link: github.com/Ducksss/payload-components

(back to top)

Acknowledgments

• Best-README-Template for the README structure.
• Payload CMS for the target CMS ecosystem.
• shadcn for the registry model Payload Components builds on.
• Fumadocs for the documentation site foundation.
• Everyone opening issues, testing installs, and contributing blocks in public.

(back to top)