Payload CMS

# Nowy projekt Payload + Next.js
npx create-payload-app@latest my-project

# Opcje podczas instalacji:
# ✓ Select a project template: blank (lub blog, website, ecommerce)
# ✓ Database: MongoDB lub PostgreSQL
# ✓ Package manager: npm, yarn, lub pnpm

my-project/
├── app/                          # Next.js App Router
│   ├── (frontend)/              # Public pages
│   │   ├── page.tsx
│   │   └── [slug]/
│   ├── (payload)/               # Admin panel (auto-generated)
│   │   └── admin/
│   │       └── [[...segments]]/
│   │           └── page.tsx
│   └── api/                     # API routes
│       └── [...payload]/
│           └── route.ts         # Payload REST API
├── collections/                  # Collection configs
│   ├── Users.ts
│   ├── Pages.ts
│   ├── Posts.ts
│   └── Media.ts
├── globals/                      # Global configs
│   ├── Settings.ts
│   └── Navigation.ts
├── blocks/                       # Reusable content blocks
│   ├── Hero.ts
│   ├── Content.ts
│   └── CallToAction.ts
├── fields/                       # Custom field configs
│   └── slug.ts
├── hooks/                        # Lifecycle hooks
│   └── populatePublishedDate.ts
├── access/                       # Access control functions
│   ├── isAdmin.ts
│   └── isOwner.ts
├── payload.config.ts             # Main Payload config
├── payload-types.ts              # Auto-generated types
└── .env

// payload.config.ts
import { buildConfig } from 'payload'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
// lub
// import { postgresAdapter } from '@payloadcms/db-postgres'
import { slateEditor } from '@payloadcms/richtext-slate'
// lub
// import { lexicalEditor } from '@payloadcms/richtext-lexical'
import { uploadthingStorage } from '@payloadcms/storage-uploadthing'
import path from 'path'
import sharp from 'sharp'

// Collections
import { Users } from './collections/Users'
import { Pages } from './collections/Pages'
import { Posts } from './collections/Posts'
import { Media } from './collections/Media'
import { Categories } from './collections/Categories'

// Globals
import { Settings } from './globals/Settings'
import { Navigation } from './globals/Navigation'

export default buildConfig({
  // Admin panel config
  admin: {
    user: Users.slug,
    meta: {
      titleSuffix: '- My CMS',
      favicon: '/favicon.ico',
      ogImage: '/og-image.png',
    },
    components: {
      // Custom admin components
      beforeDashboard: ['@/components/admin/DashboardIntro'],
    },
  },

  // Collections (repeatable content)
  collections: [Users, Pages, Posts, Media, Categories],

  // Globals (single documents)
  globals: [Settings, Navigation],

  // Rich text editor
  editor: slateEditor({}),
  // editor: lexicalEditor({}),

  // Database adapter
  db: mongooseAdapter({
    url: process.env.DATABASE_URI!,
  }),
  // db: postgresAdapter({
  //   pool: {
  //     connectionString: process.env.DATABASE_URI!,
  //   },
  // }),

  // File uploads
  upload: {
    limits: {
      fileSize: 10000000, // 10MB
    },
  },

  // TypeScript auto-generation
  typescript: {
    outputFile: path.resolve(__dirname, 'payload-types.ts'),
  },

  // GraphQL (opcjonalne)
  graphQL: {
    schemaOutputFile: path.resolve(__dirname, 'generated-schema.graphql'),
  },

  // Image processing
  sharp,

  // Plugins
  plugins: [
    // uploadthingStorage({
    //   collections: {
    //     media: true,
    //   },
    //   options: {
    //     token: process.env.UPLOADTHING_TOKEN,
    //   },
    // }),
  ],

  // CORS
  cors: [process.env.NEXT_PUBLIC_SITE_URL || ''].filter(Boolean),
  csrf: [process.env.NEXT_PUBLIC_SITE_URL || ''].filter(Boolean),
})

# .env
DATABASE_URI=mongodb://localhost:27017/payload
# lub
# DATABASE_URI=postgresql://user:password@localhost:5432/payload

PAYLOAD_SECRET=your-super-secret-key-min-32-chars
NEXT_PUBLIC_SITE_URL=http://localhost:3000

// collections/Posts.ts
import { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  labels: {
    singular: 'Post',
    plural: 'Posts',
  },
  admin: {
    useAsTitle: 'title',
    defaultColumns: ['title', 'status', 'publishedDate'],
    group: 'Content',
    description: 'Blog posts and articles',
  },
  access: {
    read: () => true,
    create: ({ req: { user } }) => Boolean(user),
    update: ({ req: { user } }) => Boolean(user),
    delete: ({ req: { user } }) => user?.role === 'admin',
  },
  versions: {
    drafts: {
      autosave: {
        interval: 300, // 5 minutes
      },
    },
    maxPerDoc: 10,
  },
  hooks: {
    beforeChange: [
      ({ data, operation }) => {
        if (operation === 'create' && !data.publishedDate) {
          data.publishedDate = new Date().toISOString()
        }
        return data
      },
    ],
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
      minLength: 3,
      maxLength: 200,
    },
    {
      name: 'slug',
      type: 'text',
      required: true,
      unique: true,
      admin: {
        position: 'sidebar',
      },
      hooks: {
        beforeValidate: [
          ({ value, data }) => {
            if (!value && data?.title) {
              return data.title
                .toLowerCase()
                .replace(/[^a-z0-9]+/g, '-')
                .replace(/(^-|-$)/g, '')
            }
            return value
          },
        ],
      },
    },
    {
      name: 'excerpt',
      type: 'textarea',
      maxLength: 300,
    },
    {
      name: 'content',
      type: 'richText',
      required: true,
    },
    {
      name: 'featuredImage',
      type: 'upload',
      relationTo: 'media',
      required: true,
    },
    {
      name: 'author',
      type: 'relationship',
      relationTo: 'users',
      required: true,
      defaultValue: ({ user }) => user?.id,
      admin: {
        position: 'sidebar',
      },
    },
    {
      name: 'categories',
      type: 'relationship',
      relationTo: 'categories',
      hasMany: true,
    },
    {
      name: 'tags',
      type: 'array',
      fields: [
        {
          name: 'tag',
          type: 'text',
          required: true,
        },
      ],
    },
    {
      name: 'status',
      type: 'select',
      defaultValue: 'draft',
      options: [
        { label: 'Draft', value: 'draft' },
        { label: 'Published', value: 'published' },
        { label: 'Archived', value: 'archived' },
      ],
      admin: {
        position: 'sidebar',
      },
    },
    {
      name: 'publishedDate',
      type: 'date',
      admin: {
        position: 'sidebar',
        date: {
          pickerAppearance: 'dayAndTime',
        },
      },
    },
    {
      name: 'seo',
      type: 'group',
      fields: [
        {
          name: 'metaTitle',
          type: 'text',
          maxLength: 60,
        },
        {
          name: 'metaDescription',
          type: 'textarea',
          maxLength: 160,
        },
        {
          name: 'ogImage',
          type: 'upload',
          relationTo: 'media',
        },
      ],
    },
  ],
}

// Wszystkie dostępne typy pól

const fields = [
  // Text fields
  { name: 'title', type: 'text' },
  { name: 'description', type: 'textarea' },
  { name: 'content', type: 'richText' },
  { name: 'code', type: 'code', admin: { language: 'typescript' } },
  { name: 'email', type: 'email' },

  // Number fields
  { name: 'price', type: 'number', min: 0, max: 10000 },

  // Date fields
  { name: 'publishedAt', type: 'date' },

  // Boolean
  { name: 'featured', type: 'checkbox' },

  // Select
  {
    name: 'status',
    type: 'select',
    options: [
      { label: 'Draft', value: 'draft' },
      { label: 'Published', value: 'published' },
    ],
  },
  {
    name: 'roles',
    type: 'select',
    hasMany: true,
    options: ['admin', 'editor', 'viewer'],
  },

  // Radio
  {
    name: 'priority',
    type: 'radio',
    options: [
      { label: 'Low', value: 'low' },
      { label: 'High', value: 'high' },
    ],
  },

  // Relationship (foreign key)
  {
    name: 'author',
    type: 'relationship',
    relationTo: 'users',
  },
  {
    name: 'categories',
    type: 'relationship',
    relationTo: 'categories',
    hasMany: true,
  },
  {
    name: 'relatedContent',
    type: 'relationship',
    relationTo: ['posts', 'pages'], // Polymorphic
    hasMany: true,
  },

  // Upload (media)
  {
    name: 'image',
    type: 'upload',
    relationTo: 'media',
  },

  // Array (repeatable nested)
  {
    name: 'socialLinks',
    type: 'array',
    fields: [
      { name: 'platform', type: 'text' },
      { name: 'url', type: 'text' },
    ],
  },

  // Group (nested object)
  {
    name: 'address',
    type: 'group',
    fields: [
      { name: 'street', type: 'text' },
      { name: 'city', type: 'text' },
      { name: 'zip', type: 'text' },
    ],
  },

  // Blocks (dynamic content)
  {
    name: 'layout',
    type: 'blocks',
    blocks: [HeroBlock, ContentBlock, CTABlock],
  },

  // Tabs (UI organization)
  {
    type: 'tabs',
    tabs: [
      {
        label: 'Content',
        fields: [
          { name: 'title', type: 'text' },
          { name: 'body', type: 'richText' },
        ],
      },
      {
        label: 'SEO',
        fields: [
          { name: 'metaTitle', type: 'text' },
          { name: 'metaDescription', type: 'textarea' },
        ],
      },
    ],
  },

  // Row (horizontal layout)
  {
    type: 'row',
    fields: [
      { name: 'firstName', type: 'text' },
      { name: 'lastName', type: 'text' },
    ],
  },

  // Collapsible
  {
    type: 'collapsible',
    label: 'Advanced Options',
    fields: [
      { name: 'customCSS', type: 'code', admin: { language: 'css' } },
    ],
  },

  // Point (geo coordinates)
  {
    name: 'location',
    type: 'point',
  },

  // JSON
  {
    name: 'metadata',
    type: 'json',
  },

  // UI (display only, no data)
  {
    type: 'ui',
    name: 'divider',
    admin: {
      components: {
        Field: () => <hr />,
      },
    },
  },
]

// collections/Media.ts
import { CollectionConfig } from 'payload'

export const Media: CollectionConfig = {
  slug: 'media',
  labels: {
    singular: 'Media',
    plural: 'Media',
  },
  admin: {
    useAsTitle: 'filename',
    group: 'Media',
  },
  access: {
    read: () => true,
  },
  upload: {
    staticDir: 'media',
    staticURL: '/media',
    imageSizes: [
      {
        name: 'thumbnail',
        width: 400,
        height: 300,
        position: 'centre',
      },
      {
        name: 'card',
        width: 768,
        height: 1024,
        position: 'centre',
      },
      {
        name: 'feature',
        width: 1920,
        height: undefined,
        position: 'centre',
      },
    ],
    adminThumbnail: 'thumbnail',
    mimeTypes: ['image/*', 'application/pdf'],
  },
  fields: [
    {
      name: 'alt',
      type: 'text',
      required: true,
    },
    {
      name: 'caption',
      type: 'text',
    },
  ],
}

// blocks/Hero.ts
import { Block } from 'payload'

export const HeroBlock: Block = {
  slug: 'hero',
  labels: {
    singular: 'Hero Section',
    plural: 'Hero Sections',
  },
  imageURL: '/blocks/hero.png',
  fields: [
    {
      name: 'heading',
      type: 'text',
      required: true,
    },
    {
      name: 'subheading',
      type: 'textarea',
    },
    {
      name: 'backgroundImage',
      type: 'upload',
      relationTo: 'media',
      required: true,
    },
    {
      name: 'cta',
      type: 'group',
      fields: [
        { name: 'label', type: 'text' },
        { name: 'link', type: 'text' },
      ],
    },
    {
      name: 'alignment',
      type: 'select',
      defaultValue: 'center',
      options: [
        { label: 'Left', value: 'left' },
        { label: 'Center', value: 'center' },
        { label: 'Right', value: 'right' },
      ],
    },
  ],
}

// blocks/Content.ts
export const ContentBlock: Block = {
  slug: 'content',
  labels: {
    singular: 'Content Block',
    plural: 'Content Blocks',
  },
  fields: [
    {
      name: 'content',
      type: 'richText',
      required: true,
    },
  ],
}

// collections/Pages.ts (using blocks)
export const Pages: CollectionConfig = {
  slug: 'pages',
  admin: {
    useAsTitle: 'title',
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'slug',
      type: 'text',
      required: true,
      unique: true,
    },
    {
      name: 'layout',
      type: 'blocks',
      blocks: [HeroBlock, ContentBlock, CTABlock, FeatureGridBlock],
      required: true,
    },
  ],
}

// access/isAdmin.ts
import { Access } from 'payload'

export const isAdmin: Access = ({ req: { user } }) => {
  return user?.role === 'admin'
}

// access/isAdminOrSelf.ts
export const isAdminOrSelf: Access = ({ req: { user } }) => {
  if (!user) return false
  if (user.role === 'admin') return true

  // Zwróć query constraint
  return {
    id: {
      equals: user.id,
    },
  }
}

// access/isOwner.ts
export const isOwner: Access = ({ req: { user } }) => {
  if (!user) return false
  if (user.role === 'admin') return true

  return {
    author: {
      equals: user.id,
    },
  }
}

// access/publishedOrAdmin.ts
export const publishedOrAdmin: Access = ({ req: { user } }) => {
  if (user?.role === 'admin') return true

  return {
    status: {
      equals: 'published',
    },
  }
}

{
  name: 'internalNotes',
  type: 'textarea',
  access: {
    read: ({ req: { user } }) => user?.role === 'admin',
    update: ({ req: { user } }) => user?.role === 'admin',
  },
}

export const Posts: CollectionConfig = {
  slug: 'posts',
  access: {
    // Kto może czytać
    read: publishedOrAdmin,

    // Kto może tworzyć
    create: ({ req: { user } }) => Boolean(user),

    // Kto może aktualizować (z query constraint)
    update: isOwner,

    // Kto może usuwać
    delete: isAdmin,

    // Admin UI access
    admin: ({ req: { user } }) => Boolean(user),
  },
  // ...
}

// app/(frontend)/blog/page.tsx
import { getPayload } from 'payload'
import configPromise from '@payload-config'

export default async function BlogPage() {
  const payload = await getPayload({
    config: configPromise,
  })

  // Find all published posts
  const { docs: posts, totalDocs } = await payload.find({
    collection: 'posts',
    where: {
      status: {
        equals: 'published',
      },
    },
    sort: '-publishedDate',
    limit: 10,
    depth: 2, // Populate relationships
  })

  return (
    <div>
      <h1>Blog ({totalDocs} posts)</h1>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>
            <a href={`/blog/${post.slug}`}>{post.title}</a>
          </li>
        ))}
      </ul>
    </div>
  )
}

// app/(frontend)/blog/[slug]/page.tsx
export default async function BlogPost({ params }: { params: { slug: string } }) {
  const payload = await getPayload({ config: configPromise })

  const { docs } = await payload.find({
    collection: 'posts',
    where: {
      slug: {
        equals: params.slug,
      },
      status: {
        equals: 'published',
      },
    },
    limit: 1,
    depth: 2,
  })

  const post = docs[0]

  if (!post) {
    notFound()
  }

  return (
    <article>
      <h1>{post.title}</h1>
      <RichText content={post.content} />
    </article>
  )
}

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

const payload = await getPayload({ config: configPromise })

// FIND (query)
const { docs, totalDocs, page, totalPages, hasNextPage } = await payload.find({
  collection: 'posts',
  where: {
    status: { equals: 'published' },
    categories: { contains: categoryId },
    publishedDate: { greater_than: '2024-01-01' },
  },
  sort: '-publishedDate',
  page: 1,
  limit: 10,
  depth: 2,
  locale: 'pl',
  fallbackLocale: 'en',
})

// FIND BY ID
const post = await payload.findByID({
  collection: 'posts',
  id: 'post-id',
  depth: 2,
})

// CREATE
const newPost = await payload.create({
  collection: 'posts',
  data: {
    title: 'New Post',
    slug: 'new-post',
    content: richTextContent,
    status: 'draft',
    author: userId,
  },
})

// UPDATE
const updatedPost = await payload.update({
  collection: 'posts',
  id: 'post-id',
  data: {
    title: 'Updated Title',
    status: 'published',
  },
})

// UPDATE MANY
const { docs: updated } = await payload.update({
  collection: 'posts',
  where: {
    status: { equals: 'draft' },
  },
  data: {
    status: 'archived',
  },
})

// DELETE
await payload.delete({
  collection: 'posts',
  id: 'post-id',
})

// DELETE MANY
await payload.delete({
  collection: 'posts',
  where: {
    status: { equals: 'archived' },
  },
})

// COUNT
const count = await payload.count({
  collection: 'posts',
  where: {
    status: { equals: 'published' },
  },
})

// GLOBALS
const settings = await payload.findGlobal({
  slug: 'settings',
})

await payload.updateGlobal({
  slug: 'settings',
  data: {
    siteName: 'Updated Site Name',
  },
})

const { docs } = await payload.find({
  collection: 'posts',
  where: {
    // Equality
    status: { equals: 'published' },
    featured: { equals: true },

    // Not equal
    status: { not_equals: 'draft' },

    // Comparison (numbers, dates)
    views: { greater_than: 100 },
    views: { greater_than_equal: 100 },
    views: { less_than: 1000 },
    views: { less_than_equal: 1000 },
    publishedDate: { greater_than: '2024-01-01' },

    // Text search
    title: { contains: 'JavaScript' },
    title: { like: '%JavaScript%' }, // SQL-like

    // Existence
    featuredImage: { exists: true },

    // Array operations
    tags: { in: ['javascript', 'typescript'] },
    tags: { not_in: ['deprecated'] },
    categories: { contains: 'category-id' },
    categories: { all: ['cat1', 'cat2'] }, // All must match

    // Logical operators
    or: [
      { status: { equals: 'published' } },
      { author: { equals: currentUserId } },
    ],

    and: [
      { status: { equals: 'published' } },
      { publishedDate: { less_than: new Date().toISOString() } },
    ],
  },
})

// Endpointy dla collection "posts":
GET    /api/posts           // Find all
GET    /api/posts/:id       // Find by ID
POST   /api/posts           // Create
PATCH  /api/posts/:id       // Update
DELETE /api/posts/:id       // Delete

// Query parameters
GET /api/posts?where[status][equals]=published
GET /api/posts?sort=-publishedDate
GET /api/posts?limit=10&page=2
GET /api/posts?depth=2

// Globals
GET  /api/globals/settings
POST /api/globals/settings

// Auth
POST /api/users/login
POST /api/users/logout
POST /api/users/me
POST /api/users/forgot-password
POST /api/users/reset-password

// Client-side fetch
const response = await fetch('/api/posts?where[status][equals]=published&limit=10', {
  headers: {
    'Content-Type': 'application/json',
    // Auth (jeśli wymagane)
    'Authorization': `JWT ${token}`,
  },
})

const { docs, totalDocs, page } = await response.json()

// Create
const newPost = await fetch('/api/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `JWT ${token}`,
  },
  body: JSON.stringify({
    title: 'New Post',
    slug: 'new-post',
    status: 'draft',
  }),
})

// hooks/populateSlug.ts
import { FieldHook } from 'payload'

export const populateSlug: FieldHook = ({ value, data }) => {
  if (!value && data?.title) {
    return data.title
      .toLowerCase()
      .replace(/[^a-z0-9]+/g, '-')
      .replace(/(^-|-$)/g, '')
  }
  return value
}

// hooks/sendNotification.ts
import { CollectionAfterChangeHook } from 'payload'

export const sendNotification: CollectionAfterChangeHook = async ({
  doc,
  operation,
  req,
}) => {
  if (operation === 'create') {
    // Send email, webhook, etc.
    await fetch('https://hooks.example.com/new-post', {
      method: 'POST',
      body: JSON.stringify({
        title: doc.title,
        author: doc.author,
      }),
    })
  }

  return doc
}

// Collection z hooks
export const Posts: CollectionConfig = {
  slug: 'posts',
  hooks: {
    // Before operations
    beforeValidate: [validateData],
    beforeChange: [populatePublishedDate],
    beforeDelete: [archiveBeforeDelete],
    beforeRead: [restrictDrafts],

    // After operations
    afterChange: [sendNotification, revalidateCache],
    afterDelete: [cleanupRelated],
    afterRead: [transformData],

    // Auth hooks (Users collection)
    afterLogin: [logLogin],
    afterLogout: [logLogout],
    afterForgotPassword: [sendResetEmail],
  },
  fields: [
    {
      name: 'slug',
      type: 'text',
      hooks: {
        beforeValidate: [populateSlug],
      },
    },
  ],
}

// globals/Settings.ts
import { GlobalConfig } from 'payload'

export const Settings: GlobalConfig = {
  slug: 'settings',
  label: 'Site Settings',
  admin: {
    group: 'Config',
  },
  access: {
    read: () => true,
    update: ({ req: { user } }) => user?.role === 'admin',
  },
  fields: [
    {
      name: 'siteName',
      type: 'text',
      required: true,
    },
    {
      name: 'siteDescription',
      type: 'textarea',
    },
    {
      name: 'logo',
      type: 'upload',
      relationTo: 'media',
    },
    {
      name: 'socialLinks',
      type: 'array',
      fields: [
        {
          name: 'platform',
          type: 'select',
          options: ['twitter', 'facebook', 'instagram', 'linkedin'],
        },
        {
          name: 'url',
          type: 'text',
        },
      ],
    },
    {
      name: 'footer',
      type: 'group',
      fields: [
        { name: 'copyright', type: 'text' },
        { name: 'showSocialLinks', type: 'checkbox' },
      ],
    },
  ],
}

// Usage
const settings = await payload.findGlobal({ slug: 'settings' })
console.log(settings.siteName)

// components/RichText.tsx
import React from 'react'
import { SerializedEditorState } from 'lexical'
// lub dla Slate:
// import { Descendant } from 'slate'

interface RichTextProps {
  content: SerializedEditorState | null
}

// Dla Lexical (domyślny w Payload 3.0)
export function RichText({ content }: RichTextProps) {
  if (!content) return null

  // Payload dostarcza komponenty do renderowania
  return (
    <div className="prose prose-lg max-w-none">
      <LexicalContent content={content} />
    </div>
  )
}

// Alternatywnie - custom rendering
import {
  JSXConvertersFunction,
  RichText as PayloadRichText,
} from '@payloadcms/richtext-lexical/react'

const converters: JSXConvertersFunction = ({ defaultConverters }) => ({
  ...defaultConverters,
  blocks: {
    ...defaultConverters.blocks,
    // Custom block rendering
    codeBlock: ({ node }) => (
      <pre className="bg-gray-900 text-white p-4 rounded-lg overflow-x-auto">
        <code>{node.fields.code}</code>
      </pre>
    ),
  },
})

export function RichTextContent({ content }: RichTextProps) {
  return (
    <PayloadRichText
      data={content}
      converters={converters}
    />
  )
}

# Dockerfile
FROM node:20-alpine AS base

FROM base AS deps
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable pnpm && pnpm install --frozen-lockfile

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN corepack enable pnpm && pnpm build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production

COPY --from=builder /app/public ./public
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/media ./media

EXPOSE 3000
CMD ["node", "server.js"]