payload-components add vs shadcn add

payload-components is built on the shadcn registry. The two commands are not rivals — payload-components add wraps the same registry delivery, then performs the Payload wiring shadcn add leaves to you.

The difference is where each one stops.

The five artifacts

A Payload layout block is live only when five artifacts exist. shadcn add produces the first; payload-components add produces all five in one pass.

shadcn add lands 1 of 5 — the other four are your TODO list. payload-components add lands 5 of 5, as one git diff you review like any PR.

What shadcn add does

shadcn add copies a registry item's files into your project and resolves its dependencies. For a self-contained React or shadcn UI component, that is the whole job: the component renders as soon as you import it.

What payload-components add adds

A Payload layout block is not self-contained. It does not render until Payload knows about it:

• it must be registered as a block in the Pages collection,
• mapped to its component in RenderBlocks,
• present in the generated payload-types.ts,
• and listed in the admin import map.

payload-components add performs those four edits for you, verifies your project against the support matrix first, and records install state in .payload-components/state.json so a second run converges instead of duplicating wiring.

When to use which

• Use shadcn add for a plain React or shadcn UI component that renders on import.
• Use payload-components add when the component is a Payload layout block that has to be registered, rendered, typed, and import-mapped before it works.

Both deliver plain source you own and can edit — no vendored framework, no lock-in.

Next

• What is a Payload component?
• Installation
• Component Catalog