Practical Payload CMS v3 guidance
Payload CMS block and installer guides
Practical Payload CMS v3 guides for installing reusable blocks, wiring collections and renderers, generating types, and fixing blocks that do not render.
Start with a proven guide
npx payload-components add hero-basic
Install a wired Payload block
Add a real block with the supported CLI, then review every file and wiring change that lands.
Follow the installation guideWire a reusable block
Follow a Payload CMS v3 block from config through registration, rendering, generated types, and the admin import map.
Read the guideFix a block that will not render
Check the four places that usually explain why a saved block does not appear on the page.
Read the guideField notes from the registry
More Payload CMS field notes
Browse implementation lessons, component design notes, and release stories from the open registry.
Templates Are Here: Six Payload Site Concepts to Explore
Explore six community-shaped Payload CMS and Next.js site concepts, trace 30 designed pages back to installable blocks, and help decide what templates should become next.
What Is a Payload CMS Block?
A practical mental model for Payload blocks, from editor input and stored data to generated types and React output.
Build Your First Payload v3 Landing Page with Next.js
Compose a real landing page from typed Payload blocks, wire the renderer, and verify the editor-to-frontend loop.
Anatomy of a Production-Ready Payload Block Config
Design explicit Payload block contracts with stable slugs, readable types, editor labels, validation, and safe field models.
How RenderBlocks Turns Payload Data into a Next.js Page
Follow a Payload layout through discriminated-union narrowing, renderer-map dispatch, wrappers, fallbacks, and React output.
Why Payload Types and the Admin Import Map Must Stay in Sync
Understand the two generated artifacts that keep a Payload schema, typed frontend, and admin component graph aligned.
Payload Block Not Rendering? Follow This Debugging Checklist
Diagnose a missing Payload block from saved document to collection registration, renderer map, generated artifacts, and frontend output.
Copying a Component Is Not the Same as Installing It
See why Payload components need registration, renderer mapping, generators, and recovery state in addition to copied source files.
Using a shadcn Registry with Payload CMS
Understand how a shadcn-compatible registry packages Payload source, public dependencies, targets, and reviewable consumer installs.
The Manifest as an Executable Wiring Contract
See how files, dependencies, source fragments, generators, and install state turn a registry item into a recoverable Payload integration.
Why We Patch Source with Text Anchors Instead of Rewriting the AST
Learn the trade-offs behind narrow text-anchor patches, explicit starter support, dedup checks, and readable installation diffs.
Designing an Idempotent Code Installer
Build install stages that converge across first runs, repeated runs, partial failures, manual edits, and explicit recovery.
Meet `payload-components doctor`
Diagnose project readiness, healthy installs, missing files, broken fragments, and partial recovery without changing the repository.
Component Variants Without Prop Explosion
Separate structural variants from content options so Payload schemas, React components, registry items, and editor choices stay understandable.
Sharing Payload Fields Across a Component Family
Reuse a stable editorial vocabulary across structural variants with real shipped source, explicit registry files, and honest generated types.
How to Choose the Right Hero for a Payload Site
Choose hero structure by message, media, action, and editorial constraints—not by whichever screenshot happens to look most dramatic.
Designing Feature Sections Editors Can Actually Maintain
Choose grid, split, steps, or bento structures by content rhythm and give Payload editors fields that remain coherent after launch.
Modeling Pricing Pages in Payload Without Hard-Coding the Design
Separate plan data, comparison content, calls to action, and structural pricing variants so editors can maintain the page safely.
Building Credible Social-Proof Sections
Model logos, testimonials, ratings, quotes, and outcomes in Payload without turning trust into an unsupported wall of decoration.
Build a Complete SaaS Homepage with Payload Components
Assemble a typed SaaS homepage from hero, proof, features, integrations, pricing, FAQ, and call-to-action blocks.
Build an Editorial Blog Frontend with Payload Post Components
Design a typed editorial source and compose index, article, related-content, metadata, and syndication surfaces in Next.js.
Designing an Accessible FAQ Block for Payload CMS
Build a maintainable FAQ content model with semantic disclosure controls, keyboard behavior, resilient state, and useful testing.
Safe Links, Forms, and Embeds in CMS-Managed Components
Define trust boundaries for editor-controlled destinations, server submissions, and third-party media without accepting arbitrary executable input.
Making Motion Feel Good Without Sacrificing Performance
Build progressive component motion with stable layout, compositor-friendly effects, reduced-motion completeness, and measured browser behavior.
Type-Safe Block Rendering Patterns for Payload and Next.js
Use Payload's discriminated unions, typed renderer maps, exhaustive checks, relationship narrowing, and wrapper contracts without spreading casts.
Why Every Live Preview Has a Demo Twin
Preserve the site/runtime boundary with static preview twins, class-mirror tests, accessibility isolation, and component-level visual baselines.
Visual Regression Testing a Component Registry
Capture stable preview routes, compare platform baselines, gate component coverage, and review intentional visual change without hiding skips.
How to Add a Payload Component End to End
Ship source, manifest, registry entry, component docs, demo twin, installer coverage, and visual evidence as one complete contribution.
Building a Reproducible shadcn-Compatible Registry
Make source registry builds deterministic, schema-valid, path-safe, and verifiable from a clean checkout before public distribution.
Open Source Requires Provenance, Not Just a License File
Record upstream authorship, licenses, adaptations, assets, and distribution obligations so reusable source keeps its history.
How Real Installs Should Shape an Open-Source Component Roadmap
Turn install evidence, reproducible friction, public issues, and complete contributions into a community roadmap that reflects real Payload projects.
Payload CMS block not showing? Check the four wiring steps
Find the missing Payload CMS block registration, renderer mapping, generated type, or admin import map step.
Hello — and why I built Payload Components
A quick hello, the itch that started this, and what you'll find on this blog.