Installation

Payload Components currently targets Payload v3 projects using Next.js App Router and the supported website-style block layout shape.

Requirements

The installer verifies the target project shape before it mutates anything. If a requirement is missing, it stops rather than leaving a half-wired repo.

Your project must run these majors:

Dependency	Version
`payload`	v3
`next`	v15 or v16

…and it must already contain the website-style block layout the installer patches into:

components.json

payload.config.ts

RenderBlocks.tsx

index.ts

Plus package.json scripts for generate:types and generate:importmap, which the CLI runs after wiring.

Install a component

Pick a component and run its add command from the root of your Payload project. The component pages show the exact command for every block; examples:

npx payload-components add hero-basic

npx payload-components add feature-grid-basic

npx payload-components add logo-cloud-grid

npx payload-components add content-columns

npx payload-components add integration-grid

What the CLI does

The wrapper CLI owns the Payload-specific work that direct registry installation cannot handle:

Validate the target project shape — refuse to touch a repo that isn't a supported Payload v3 + Next.js project.

Build or resolve the registry item and install source files through the shadcn registry flow.

Apply Payload layout and render fragments — register the block in RenderBlocks and the Pages layout field.

Install missing component dependencies so the block compiles in your project.

Run post-install scripts (generate:types, generate:importmap) and write .payload-components/state.json.

Doctor

Run a read-only health check before or after installing components:

npx payload-components doctor

doctor validates the supported project shape, required post-install scripts, and recorded component installs in .payload-components/state.json. It exits non-zero when files, Payload fragments, dependency declarations, or install state need attention.

Idempotency

Running the same install twice should not duplicate imports, block registrations, or layout entries. The installer verifies files, fragments, dependencies, and recorded state before deciding whether any work is needed.

Direct registry installs

Every block is also published to a public, shadcn-compatible registry, so you can pull a block's files with the plain shadcn CLI — useful for inspecting a block or dropping one into a non-Payload project.

{
  "registries": {
    "@payload-components": "https://www.payload-components.xyz/r/{name}.json"
  }
}

Then add any block by name:

pnpm dlx shadcn@latest add @payload-components/hero-basic

Or install a single item straight from its URL, without configuring the namespace:

pnpm dlx shadcn@latest add https://www.payload-components.xyz/r/hero-basic.json

A direct shadcn add only copies the block's source files and its shadcn UI dependencies. It does not register the block in RenderBlocks, wire the Pages layout field, install Payload dependencies, or run generate:types and generate:importmap. For a real Payload project, use payload-components add — it does all of that and records install state.