payload
/payload
Payload CMS 3.0 knowledge base - collections, multi-tenancy, frontend integration. Use when setting up Payload CMS, configuring collections, implementing multi-tenancy, or integrating CMS with Next.js frontend.
- Author
- PIXARTSeu ↗
- Repository
- Synapse ↗
- Licence
- AGPL-3.0
- Last repository change
- 15.09.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 15.09.2026, without references to retired models or APIs.
AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.
What it does and when to use it
Payload CMS 3.0 knowledge base - collections, multi-tenancy, frontend integration. Use when setting up Payload CMS, configuring collections, implementing multi-tenancy, or integrating CMS with Next.js frontend.
Original author description
Payload CMS 3.0 knowledge base - collections, multi-tenancy, frontend integration. Use when setting up Payload CMS, configuring collections, implementing multi-tenancy, or integrating CMS with Next.js frontend.
How it works
- Installazione
- Configurazione Base
- Collections Overview
- Reusable Fields (Project-Specific)
- Access Control Patterns (Multi-Tenancy)
- Frontend Integration
- Revalidation API Route
- Localization Config
- Best Practices
SKILL.md preview
---
name: payload
description: Payload CMS 3.0 knowledge base - collections, multi-tenancy, frontend integration. Use when setting up Payload CMS, configuring collections, implementing multi-tenancy, or integrating CMS with Next.js frontend.
version: 1.0.0
context: "bash .Claude/scripts/load_project_context.sh"
---
# Payload CMS 3.0 Skill
Documentazione per Payload CMS 3.0 con Next.js e MongoDB.
## Installazione
```bash
# Nuovo progetto
pnpm create payload-app@latest
# Aggiungere a progetto Next.js esistente
pnpm add payload @payloadcms/next @payloadcms/db-mongodb @payloadcms/richtext-lexical
```
## Configurazione Base
**payload.config.ts** deve includere:
- Database adapter: `mongooseAdapter` con MongoDB URI
- Editor: `lexicalEditor` per rich text
- Collections: Users, Pages, Posts, Media, Categories, Tenants
- Globals: Header, Footer, Settings
- Plugins: seoPlugin, formBuilderPlugin, nestedDocsPlugin, redirectsPlugin, searchPlugin
- Localization: it, en, cs (defaultLocale: 'it')
- TypeScript output: `payload-types.ts`
## Collections Overview
| Collection | Key Fields | Notes |
|------------|-----------|-------|
| **Users** | name, email, roles (admin/editor/user), tenant | Auth enabled, JWT saveToJWT |
| **Pages** | title, slug, status (draft/published), layout (blocks), meta | Drafts enabled, revalidation hooks |
| **Posts** | title, slug, excerpt, content, featuredImage, author, categories, status | Drafts enabled, blog content |
| **Media** | alt, caption, tenant | imageSizes: thumbnail, card, tablet, desktop |
| **Categories** | name | Taxonomy for posts |
| **Tenants** | name, slug, domain, settings (colors, logo), locales | Multi-tenancy root |
## Reusable Fields (Project-Specific)
### slugField()
Auto-generates slug from title, required, unique, sidebar position.
```typescript
export const slugField = (fieldToUse = 'title'): Field => ({
name: 'slug',
type: 'text',
required: true,
unique: true,
admin: { position: 'sidebar' },
hooks: {
beforeValidate: [
({ value, data }) => {
if (!value && data?.[fieldToUse]) {
return formatSlug(data[fieldToUse])
}
return value
},
],
},
})
```
### tenantField
Relationship to Tenants collection, auto-filled from user.tenant, hidden from admins.
```typescript
export const tenantField: Field = {
name: 'tenant',
type: 'relationship',
relationTo: 'tenants',
required: true,
admin: {
position: 'sidebar',
condition: (data, siblingData, { user }) => !user?.roles?.includes('admin'),
},
hooks: {
beforeChange: [
({ req, value }) => {
if (!value && req.user?.tenant) {
return req.user.tenant
}
return value
},
],
},
}
```
## Access Control Patterns (Multi-Tenancy)
### tenantReadAccess
- Admins: read all
- Others: read only their tenant's data
```typescript
export const tenantReadAccess: Access = ({ req: { user } }) => {
if (user?.roles?.includes('admin')) return true
if (user?.tenant) {
return { tenant: { equals: user.tenant } }
}
return false
}
```
### tenantWriteAccess
- Admins: write all
- Editors with tenant: write only their tenant's data
```typescript
export const tenantWriteAccess: Access = ({ req: { user } }) => {
if (user?.roles?.includes('admin')) return true
if (user?.roles?.includes('editor') && user?.tenant) {
return { tenant: { equals: user.tenant } }
}
return false
}
```
## Frontend Integration
### getPayloadClient (Singleton)
```typescript
// lib/payload.ts
import { getPayload } from 'payload'
import config from '@payload-config'
let cached = global.payload
if (!cached) {
cached = global.payload = { client: null, promise: null }
}
export const getPayloadClient = async () => {
if (cached.client) return cached.client
if (!cached.promise) {
cached.promise = getPayload({ config })
}
cached.client = await cached.promise
return cached.client
}
```
### Fetch Data with Tenant Filter
```typescript
export async function getPage(slug: string, tenant?: string) {
const payload = await getPayloadClient()
const { docs } = await payload.find({
collection: 'pages',
where: {
slug: { equals: slug },
status: { equals: 'published' },
...(tenant && { tenant: { equals: tenant } }),
},
depth: 2,
})
return docs[0] || null
}
```
## Revalidation API Route
```typescript
// app/api/revalidate/route.ts
import { revalidatePath, revalidateTag } from 'next/cache'
import { NextRequest, NextResponse } from 'next/server'
export async function GET(request: NextRequest) {
const path = request.nextUrl.searchParams.get('path')
const tag = request.nextUrl.searchParams.get('tag')
const secret = request.nextUrl.searchParams.get('secret')
if (secret !== process.env.REVALIDATION_SECRET) {
return NextResponse.json({ message: 'Invalid secret' }, { status: 401 })
}
if (path) {
revalidatePath(path)
return NextResponse.json({ revalidated: true, path })
}
if (tag) {
revalidateTag(tag)
return NextResponse.json({ revalidated: true, tag })
}
return NextResponse.json({ message: 'Missing path or tag' }, { status: 400 })
}
```
## Localization Config
```typescript
// payload.config.ts
export default buildConfig({
localization: {
locales: [
{ label: 'Italiano', code: 'it' },
{ label: 'English', code: 'en' },
{ label: 'Cestina', code: 'cs' },
],
defaultLocale: 'it',
fallback: true,
},
})
```
## Best Practices
1. **Always type** - Use `payload-types.ts` generated from schema
2. **Access control** - Never trust frontend, enforce in hooks
3. **Hooks for side effects** - Use beforeChange/afterChange for revalidation
4. **Drafts** - Enable versions with drafts for content editing
5. **Multi-tenancy** - Always filter queries by tenant
6. **Image optimization** - Use imageSizes for responsive images
7. **Caching** - Use revalidateTag for granular cache invalidation
Files in this package (4)
- SKILL.md 6 KB
- learnings.md 1 KB
- evals/evals.json 1 KB
- evals/trigger_evals.json 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · PIXARTSeu/Synapse | 100 | AGPL-3.0 |
| payloadcms/payload | 95 | MIT |
Database snapshot: 13.11.2026 · package version 6b1e43ba6419 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100payload-cms
Payload is an open-source, code-first headless CMS and application framework that runs inside a Next.js app, with collections defined in TypeScript. Use this skill when defining collections in TypeScript, configuring access control, customizing the admin panel, or integrating… - 90pixarts/multitenancy
Payload CMS multi-tenancy guide for Pixarts - tenant structure, access control, collections, hooks. Use when setting up multi-tenant CMS, configuring tenant access control, or implementing tenant-scoped data. - 95payloadcms
Operate Payload CMS (Next.js-native headless CMS) in repo workflows: bootstrap a Payload app, configure collections/globals, run local dev + migrations, and ship safe content-model changes. Use when the request mentions Payload CMS, payload config, collection schema, admin… - 90payload-cms
Build, extend, deploy and debug websites on Payload CMS (payloadcms.com): collections, blocks and layout builder, live preview, drafts, plugins, Postgres or Mongo, Vercel, migrations, plus cloning or rebuilding an existing site (including payloadcms.com itself) onto Payload. Use… - 100payloadcms-ops
Payload CMS 3 (Next.js-native) architecture - collections, globals, fields, access control, hooks, Local API, storage adapters, and database (Postgres/MongoDB/SQLite). Use for: payload, payloadcms, payload cms, payload 3, collection config, access control, payload hooks, local… - 100project-health-check
Comprehensive health check of a Next.js/Payload CMS project. Use when user asks to "check the project", "audit the codebase", "what's the state of the project", "project health", or before a major release. Checks TypeScript errors, build status, missing env vars, i18n…