Vadym/obsidian

Fork 0

Vadym Samoilenko d08ae38b33 wiki: auto-compile 2026-05-15 (1 log(s), 273 articles)

2026-05-15 15:45:11 +01:00

7.1 KiB

Raw Permalink Blame History

title

aliases

PayloadCMS — Getting Started

Overview

Payload is a code-first, open-source Next.js fullstack framework that acts as a CMS, enterprise tool builder, or headless commerce platform. Write a payload.config.ts and get an auto-generated Admin Panel, REST/GraphQL/Local APIs, database schema with migrations, auth, and file upload out of the box. Self-hostable anywhere Node.js runs, including Vercel serverless.

Key Concepts

Config — central payload.config.ts file; fully typed JS object; everything derives from it
Collections — groups of Documents sharing a schema (e.g. pages, posts, users)
Globals — singleton Documents (e.g. site header, nav); same APIs as Collections but one doc only
Fields — schema building blocks; define DB columns + Admin UI simultaneously
Hooks — lifecycle callbacks (before/after read, create, update, delete)
Access Control — per-collection/global functions controlling what each user can do
Local API — direct-to-DB Node.js API, zero HTTP overhead, fully typed
REST API — auto-mounted at /api/<collection-slug>
GraphQL API — auto-mounted at /api/graphql, playground at /api/graphql-playground
Admin Panel — Next.js App Router React app, auto-generated from config, fully extensible

Requirements

Node.js 24.15.0+
Next.js 16.2.6+
pnpm (preferred), npm, or yarn 2+
One DB: MongoDB, PostgreSQL, or SQLite

API / Config Reference

Minimal `payload.config.ts`

import sharp from 'sharp'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
import { buildConfig } from 'payload'

export default buildConfig({
  editor: lexicalEditor(),
  collections: [],
  secret: process.env.PAYLOAD_SECRET || '',
  db: mongooseAdapter({
    url: process.env.DATABASE_URL || '',
  }),
  sharp,
})

Core TypeScript types

import { Config, CollectionConfig, GlobalConfig, Field } from 'payload'
import type { Config, SanitizedConfig } from 'payload'

`tsconfig.json` path alias (required)

{
  "compilerOptions": {
    "paths": {
      "@payload-config": ["./payload.config.ts"]
    }
  }
}

`next.config.js` wrapper (required)

import { withPayload } from '@payloadcms/next/withPayload'

const nextConfig = {}

export default withPayload(nextConfig)

next.config must be ESM — either add "type": "module" to package.json or use .mjs extension.

Code Examples

Quickstart

npx create-payload-app
# or target a template:
npx create-payload-app@latest -t website
npx create-payload-app@latest -t blank

Manual install packages

pnpm i payload @payloadcms/next
pnpm i @payloadcms/richtext-lexical sharp graphql
pnpm i @payloadcms/db-mongodb   # or db-postgres, db-sqlite

Local API usage in React Server Component

import config from '@payload-config'
import { getPayload } from 'payload'

const MyServerComponent: React.FC = async () => {
  const payload = await getPayload({ config })
  const findResult = await payload.find({ collection: 'pages' })
  // findResult.docs is typed as Page[]
}

REST API

fetch('https://localhost:3000/api/pages')
  .then((res) => res.json())
  .then((data) => console.log(data))

App folder structure after install

app/
├─ (payload)/      # Payload files — do NOT edit
├─ (my-app)/       # Your frontend files

Package Architecture

Package	Role
`payload`	Core business logic, Local API, TypeScript types
`@payloadcms/next`	Admin Panel, REST API, GraphQL HTTP layer
`@payloadcms/ui`	Reusable Admin UI React components
`@payloadcms/db-*`	Database adapters (one per project)
`@payloadcms/richtext-lexical`	Rich text editor (optional)
`@payloadcms/graphql`	GraphQL layer (bundled in `@payloadcms/next`)

Use Cases

Use Case	Description	Quickstart
Headless CMS	Website content management with Live Preview, redirects, form builder, visual editing	`npx create-payload-app@latest -t website`
Enterprise Tool	Internal apps — SSO auth, access control, admin UI, REST/GraphQL, migrations all built-in	`npx create-payload-app@latest -t blank`
Headless Commerce	Full storefront without Shopify — products, catalogs, media, orders in one backend; offload only payments (Stripe)	`npx create-payload-app@latest -t blank`
Digital Asset Management	API-first tagging/sorting/querying, folder organization, file versioning, bulk upload, media access control	`npx create-payload-app@latest -t blank`

When to Use / Avoid

Use Payload when

Data ownership and privacy matter (no vendor lock-in)
Building a Next.js site that needs a CMS — install in existing repo
Custom business logic beyond a typical headless CMS
Need to reuse data outside of a SaaS API
Serverless deploy on Vercel is a requirement

Avoid Payload when

Project can be managed fully with code, no admin UI needed
Site fits within Webflow / Framer constraints
Already have a full DB and just need data visualization
Certain you'll never need code/data ownership

Gotchas

All official Payload packages must use matching version numbers — mixing versions breaks things
withPayload is ESM only; require() in next.config.js will fail
next.cacheComponents has partial compatibility — not fully supported alongside Payload
yarn 1.x is not supported; use pnpm, npm, or yarn 2+
The (payload) app folder files are not meant to be edited and will not regenerate
sharp is optional but required for image cropping, resizing, focal point selection
graphql package must be in your package.json explicitly if you use GraphQL queries

Key Takeaways

Payload is a code-first Next.js fullstack framework — not a SaaS; you own your data and schema
One config file (payload.config.ts) drives Admin Panel, DB schema, REST/GraphQL/Local APIs, auth, uploads simultaneously
Four distinct use cases: Headless CMS, Enterprise Tool, Headless Commerce, DAM — all from the same tool
No click-ops — schema is always version controlled; non-technical users operate via the generated Admin UI
MIT licensed, self-hostable on any Node.js host including Vercel serverless
Avoid if: no admin UI needed, project fits Webflow/Framer, or you already have a complete DB stack

7.1 KiB Raw Permalink Blame History