obsidian/wiki/payloadcms/getting-started.md

---
title: "PayloadCMS — Getting Started"
aliases: [what-is-payload, payload-overview]
tags: [payloadcms, tech-patterns, cms, nextjs, fullstack]
sources: [getting-started__what-is-payload.md, getting-started__installation.md, getting-started__concepts.md]
created: 2026-05-15
updated: 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`) |

## 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

## Related

- [[wiki/payloadcms/configuration|Payload Config — Overview]]
- [[wiki/payloadcms/concepts-overview|Core Concepts]]
- [[wiki/payloadcms/installation|Installation]]
- [[wiki/payloadcms/collection-config|Collection Config]]
- [[wiki/payloadcms/hooks|Hooks]]
- [[wiki/payloadcms/access-control|Access Control]]
- [[wiki/payloadcms/ecommerce|Ecommerce]]
- [[wiki/payloadcms/upload|Upload & Media]]