Architecture

Payload Components is two projects living in one repository — and they deliberately never share a Payload runtime.

The two responsibilities are:

1. Run a documentation and catalog site.
2. Build, validate, and distribute Payload component installs.

Those responsibilities should not share a Payload runtime.

Site runtime

The site runtime is Fumadocs on Next.js. Everything it needs lives in the app tree:

• src/app contains the app router routes.
• content/docs contains MDX documentation.
• source.config.ts defines the Fumadocs MDX collection.
• src/lib/source.ts exposes the loaded docs source.
• src/app/api/search/route.ts exposes Fumadocs search.

AI-readable surfaces

The site exposes the same docs in browser and machine-readable formats:

• /llms.txt publishes the concise source map for AI crawlers.
• /llms-full.txt publishes the compiled documentation body.
• /llms.mdx/docs/**/content.md publishes each docs page as markdown.
• JSON-LD marks the site, CLI, FAQ, component catalog, and docs articles for structured extraction.

Component runtime

The component runtime is external. A component installs into a supported Payload v3 + Next.js project, where the Payload-specific files actually live:

• block configs
• frontend block components
• RenderBlocks registration fragments
• Pages collection layout fragments
• generate:types and generate:importmap post-install tasks

Registry source

The shadcn-compatible registry reads source files from payload-components/source and emits public JSON to public/r.

That keeps Payload-specific component source out of the Fumadocs app tree while preserving install targets like ~/src/blocks/HeroBasic/Component.tsx.

Component families and shared code

A component family ships one installable component per structural variant — logo-cloud-grid, logo-cloud-marquee, logo-cloud-inline — each its own registry item and manifest. Variant selection is the catalog and the install command, never an interactive prompt. Content-level variation (optional or extra editor fields) lives in the Payload block config, not a separate component.

Variants that share fields or markup reference a common source file under payload-components/source/blocks/shared, installed once into the consumer repo — for example ~/src/blocks/shared/logoCloudFields.ts — and composed by each variant config as fields: [...logoCloudFields, /* variant-specific */]. Editing the shared file updates every installed variant; re-running an install never overwrites an edited copy. Internal shared modules ship as registry files, not registryDependencies (which resolve only public shadcn components).

Why this split matters