Skip to content
Skills Library
Programming · Learning & explanation

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.

Repository
Synapse ↗
Licence
AGPL-3.0
Last repository change
15.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.09.2026, without references to retired models or APIs.

Licence

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

  1. Installazione
  2. Configurazione Base
  3. Collections Overview
  4. Reusable Fields (Project-Specific)
  5. Access Control Patterns (Multi-Tenancy)
  6. Frontend Integration
  7. Revalidation API Route
  8. Localization Config
  9. Best Practices
Original SKILL.md headings · 222 lines, 736 words
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

RepositoryScoreLicence
This page · PIXARTSeu/Synapse100AGPL-3.0
payloadcms/payload95MIT

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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.