159 lines
4.8 KiB
Markdown
159 lines
4.8 KiB
Markdown
---
|
|
tags: [payloadcms, tech-patterns]
|
|
topic: payloadcms
|
|
sources: [getting-started__what-is-payload.md, getting-started__installation.md, getting-started__concepts.md]
|
|
created: 2026-05-15
|
|
---
|
|
|
|
# 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`
|
|
|
|
```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
|
|
|
|
```ts
|
|
import { Config, CollectionConfig, GlobalConfig, Field } from 'payload'
|
|
import type { Config, SanitizedConfig } from 'payload'
|
|
```
|
|
|
|
### `tsconfig.json` path alias (required)
|
|
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"paths": {
|
|
"@payload-config": ["./payload.config.ts"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### `next.config.js` wrapper (required)
|
|
|
|
```js
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```tsx
|
|
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
|
|
|
|
```ts
|
|
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`) |
|
|
|
|
## 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
|
|
|
|
## Related
|
|
|
|
- [[wiki/payloadcms/configuration|Configuration]]
|
|
- [[wiki/payloadcms/fields|Fields]]
|
|
- [[wiki/payloadcms/hooks|Hooks]]
|