payload-cms

Payload CMS in this starter

Payload is a Next-native CMS: it installs into this app's app/ directory rather than running as a separate service. The database is Supabase Postgres (see the supabase-db skill), media goes to Supabase Storage over its S3-compatible API.

Verified against Payload 3.88.0 (2026-08). Payload 4 is in canary — do not use it here without checking the peer ranges yourself.

0. Pre-flight — three things that break the install

1. Next.js version. @payloadcms/[email protected] peer-requires next >=16.2.6 <17. The starter is on 16.3.1, which satisfies it — but check, don't assume, since both sides move:

   node -p "require('./package.json').dependencies.next"
   npm view @payloadcms/next peerDependencies
   

   If Next is below the floor, bump it and eslint-config-next together.
2. ESM. next.config.ts must be ESM to wrap with withPayload. This starter already uses next.config.ts with ESM syntax — check before assuming.
3. A Supabase project must exist with both connection strings to hand. Run the supabase-db skill first if it does not.

Confirm the collection list with the user before writing any config. Derive the proposal from what the site actually renders — read src/views/** and the mock data in src/data/mocks/ and name real content types, not a generic posts.

1. Install

yarn add payload @payloadcms/next @payloadcms/db-postgres \
         @payloadcms/richtext-lexical @payloadcms/storage-s3 graphql sharp

sharp is required for image resizing. graphql is a hard peer dep even if you never use the GraphQL API.

2. src/payload.config.ts

import path from 'path'
import { fileURLToPath } from 'url'
import { buildConfig } from 'payload'
import { postgresAdapter } from '@payloadcms/db-postgres'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
import { s3Storage } from '@payloadcms/storage-s3'
import sharp from 'sharp'

import { Media } from './collections/media'
import { Pages } from './collections/pages'

const dirname = path.dirname(fileURLToPath(import.meta.url))

export default buildConfig({
  admin: {
    user: 'users',
    importMap: { baseDir: path.resolve(dirname) },
  },
  collections: [Pages, Media],
  editor: lexicalEditor(),
  secret: process.env.PAYLOAD_SECRET || '',
  typescript: { outputFile: path.resolve(dirname, 'payload-types.ts') },
  db: postgresAdapter({
    pool: { connectionString: process.env.DATABASE_URL || '' },
    // Schema is pushed automatically in dev. In production this must be false —
    // ship migrations instead, or a deploy can rewrite the live schema.
    push: process.env.NODE_ENV !== 'production',
  }),
  plugins: [
    s3Storage({
      collections: { media: true },
      bucket: process.env.S3_BUCKET || '',
      config: {
        endpoint: process.env.S3_ENDPOINT,      // https://<ref>.storage.supabase.co/storage/v1/s3
        region: process.env.S3_REGION,          // e.g. eu-central-1
        forcePathStyle: true,                   // REQUIRED for Supabase
        credentials: {
          accessKeyId: process.env.S3_ACCESS_KEY_ID || '',
          secretAccessKey: process.env.S3_SECRET_ACCESS_KEY || '',
        },
      },
    }),
  ],
  sharp,
})