Vadym/obsidian
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
obsidian/wiki/payloadcms/concepts-overview.md
Vadym Samoilenko 1b7691850f vault backup: 2026-05-15 15:43:24
2026-05-15 15:43:24 +01:00

4.3 KiB
Raw Blame History

title aliases tags sources created updated
Payload CMS — Core Concepts
payload-concepts
payload-overview-concepts
payloadcms
concepts
getting-started
api
collections
fields
raw/getting-started__concepts.md
2026-05-15 2026-05-15

Core Concepts at a Glance

Concept What it is
Config Central buildConfig() object — fully-typed, infinitely extensible
Database Adapter-agnostic layer (Postgres, MongoDB, SQLite, Vercel Postgres)
Collections Groups of Documents sharing a common schema; stored per DB table/collection
Globals Single-document singletons (site settings, nav, banners)
Fields Schema building blocks; drive both DB storage and Admin UI
Hooks Side effects on Document lifecycle events (before read, after create, …)
Authentication Built-in user auth with cookies, JWT, API keys, or custom strategies
Access Control Per-document/field read/write rules; also controls Admin Panel visibility
Admin Panel Auto-generated Next.js (App Router) React UI

Three APIs — All Share the Same Query Language

Local API ──► direct DB (Node.js, no HTTP overhead)
REST API  ──► /api/<collection>          (standard HTTP)
GraphQL   ──► /api/graphql               (+ /api/graphql-playground)

Local API (fastest)

  • Direct-to-database access from any server-side context
  • Fully typed TypeScript, works in RSC, Hooks, Access Control
import { getPayload } from 'payload'
import config from '@payload-config'

const payload = await getPayload({ config })
const result = await payload.find({ collection: 'pages' }) // PaginatedDocs<Page>

REST API

  • Auto-mounted at /api — zero config required
  • Full CRUD + auth routes out of the box
fetch('https://localhost:3000/api/pages').then(r => r.json())

GraphQL API

  • Auto-generated queries/mutations at /api/graphql
  • Playground at /api/graphql-playground
  • Compatible with graphql-request, @apollo/client, etc.

Package Structure

Package Responsibility
payload Core ORM + business logic (find/create/update/delete, hooks, access, validation)
@payloadcms/next Admin Panel (React/Next.js) + HTTP layer (REST + GraphQL)
@payloadcms/graphql GraphQL — optional, bundled with @payloadcms/next; needs graphql in package.json
@payloadcms/ui UI component library; re-exportable for custom extensions
@payloadcms/db-postgres PostgreSQL adapter
@payloadcms/db-vercel-postgres Vercel Postgres adapter
@payloadcms/db-mongodb MongoDB (Mongoose) adapter
@payloadcms/db-sqlite SQLite (Drizzle/libSQL) adapter
@payloadcms/richtext-lexical Lexical rich text — optional

Version sync rule: All official @payloadcms/* packages must always be on the same version.

Key Takeaways

  • Config is the single source of truth — collections, globals, fields, auth, plugins all live there
  • Payload is database-agnostic — swap adapters without changing business logic
  • Collections = many docs, Globals = one doc — both use the same Fields + Hooks system
  • Local API is the go-to for server-side code — faster than REST, fully typed, no HTTP overhead
  • All three APIs use the same query language — learn once, apply everywhere
  • Package is modular — only pay (in bundle size/deps) for what you use; GraphQL and rich text are opt-in
  • Admin Panel is auto-generated but fully customizable via slots, custom components, and custom views

Related Articles

Sources