No native build steps (pod install / Android linking) are required. Payload runs fully in Node.js. If deploying to Vercel Edge or Cloudflare Workers, use the appropriate adapter packages (@payloadcms/db-vercel-postgres or @payloadcms/db-d1).

Project setup

1. Scaffold or copy source into your project root. If using an existing Next.js app, install the packages above and create a payload.config.ts at your project root.

2. Configure next.config.mjs to wrap your config with the Payload plugin:

   import { withPayload } from '@payloadcms/next/withPayload'
   /** @type {import('next').NextConfig} */
   const nextConfig = {}
   export default withPayload(nextConfig)
   

3. Create payload.config.ts:

   import { buildConfig } from 'payload'
   import { postgresAdapter } from '@payloadcms/db-postgres'
   import { lexicalEditor } from '@payloadcms/richtext-lexical'
   
   export default buildConfig({
     secret: process.env.PAYLOAD_SECRET!,
     db: postgresAdapter({ pool: { connectionString: process.env.DATABASE_URI! } }),
     editor: lexicalEditor({}),
     collections: [],
   })
   

4. Add the Payload API route handler at app/(payload)/api/[...slug]/route.ts:

   export { GET, POST, DELETE, PATCH } from '@payloadcms/next/handlers'
   

5. Add the admin route at app/(payload)/admin/[[...segments]]/page.tsx:

   export { default } from '@payloadcms/next/views/Root'
   

6. Set environment variables:

   PAYLOAD_SECRET=your-random-secret-at-least-32-chars
   DATABASE_URI=postgres://user:pass@localhost:5432/mydb
   NEXT_PUBLIC_SERVER_URL=http://localhost:3000
   

7. Extend tsconfig.json from the base if using the monorepo approach:

   { "extends": "./tsconfig.base.json", "include": ["**/*.ts", "**/*.tsx"] }
   

8. Run npx payload generate:types to produce payload-types.ts after defining collections.

Public API

config (from examples/astro/payload/src/index.ts)

import { config } from './payload/src/index'
// typeof config: SanitizedConfig (Payload's fully resolved configuration object)

The default export re-exported as config is the sanitized Payload configuration object built by buildConfig(). Pass it to getPayload({ config }) in server-side code to obtain a Payload client instance. Use this in non-Next.js hosts (Astro, Express, Cloudflare Workers) where you import the config manually rather than relying on the Next.js plugin auto-detection.

useAuth (from examples/auth/src/app/(app)/_providers/Auth)

import { useAuth } from './_providers/Auth'

const {
  user,          // Currently authenticated user object or null
  login,         // (credentials: { email: string; password: string }) => Promise<User>
  logout,        // () => Promise<void>
  setUser,       // (user: User | null) => void
} = useAuth()

A React context hook that exposes the current session state. Call login with email/password to authenticate; call logout to clear the session. Reads the HTTP-only cookie set by Payload's /api/users/login endpoint. Use this in any client component that needs to gate UI by auth state.

AccountForm (from examples/auth/src/app/(app)/account/AccountForm/index.tsx)

import { AccountForm } from './(app)/account/AccountForm'
// React.FC — no props required

A client component rendering a controlled form (via react-hook-form) that PATCHes /api/users/:id to update the logged-in user's name, email, and optionally password. Consume useAuth internally to read user.id and call setUser after a successful update. Drop this directly into an account-settings page.

CreateAccountForm (from examples/auth/src/app/(app)/create-account/CreateAccountForm/index.tsx)

import { CreateAccountForm } from './(app)/create-account/CreateAccountForm'
// React.FC — no props required

Posts to /api/users to create a new user, then calls login from useAuth to immediately authenticate. Reads the ?redirect query parameter from useSearchParams to redirect after signup. Use this wherever you need a self-service registration flow backed by Payload's Users collection.

Working examples

Scenario - Fetching collection documents server-side (RSC)

Query a Payload collection from a Next.js React Server Component without an HTTP round-trip by using the local API.

// app/posts/page.tsx
import { getPayload } from 'payload'
import config from '@/payload.config'

export default async function PostsPage() {
  const payload = await getPayload({ config })

  const { docs } = await payload.find({
    collection: 'posts',
    where: { _status: { equals: 'published' } },
    limit: 20,
  })

  return (
    <ul>
      {docs.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

Scenario - Client-side login with useAuth

Wire up the exported LoginForm pattern using the useAuth hook in a custom login page.

// app/(app)/login/page.tsx
'use client'
import { useCallback, useState } from 'react'
import { useAuth } from '../_providers/Auth'
import { useRouter } from 'next/navigation'

export default function LoginPage() {
  const { login } = useAuth()
  const router = useRouter()
  const [error, setError] = useState<string | null>(null)

  const handleSubmit = useCallback(async (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault()
    const fd = new FormData(e.currentTarget)
    try {
      await login({
        email: fd.get('email') as string,
        password: fd.get('password') as string,
      })
      router.push('/account')
    } catch {
      setError('Invalid credentials.')
    }
  }, [login, router])

  return (
    <form onSubmit={handleSubmit}>
      {error && <p>{error}</p>}
      <input name="email" type="email" required />
      <input name="password" type="password" required />
      <button type="submit">Log in</button>
    </form>
  )
}

Scenario - REST API user registration (no React)

Create a user account using Payload's REST endpoint from a plain TypeScript script or integration test.

// scripts/seed-user.ts
async function createUser(email: string, password: string) {
  const res = await fetch(`${process.env.NEXT_PUBLIC_SERVER_URL}/api/users`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, password }),
  })

  if (!res.ok) {
    const text = await res.text()
    throw new Error(`Failed to create user: ${res.status} ${text}`)
  }

  const data = await res.json()
  console.log('Created user:', data.doc.id)
  return data.doc
}

createUser('admin@example.com', 'supersecret123').catch(console.error)

File walkthrough

• .claude/ - Contains custom slash-command definitions (analyze-issue.md, triage.md) and shell hooks for AI-assisted development workflows in this monorepo.
• .claude-plugin/ - Marketplace manifest declaring this repo as a Claude plugin with tool and skill metadata.
• .cursor/ - MCP server connection config for the Cursor IDE, mirroring .mcp.json.
• .github/ - Complete CI/CD pipeline: GitHub Actions workflows, issue/PR templates, auto-triage actions, and release-commenter automation.
• .stylelint/ - Shared Stylelint rules and order configuration extended by all packages with CSS.
• .vscode/ - Recommended extensions, workspace settings, and debug launch configurations.
• app/ - The public-facing Payload documentation and demo Next.js application deployed at payloadcms.com.
• docs/ - MDX source files for all official Payload documentation pages.
• examples/ - Self-contained runnable projects (auth, Astro, multitenancy, live preview, etc.) used as integration references.
• packages/ - The publishable npm packages: payload core, @payloadcms/next, database adapters, rich text editor, plugins, and UI.
• public/ - Static images, fonts, and assets served by the documentation site.
• scripts/ - Monorepo automation: version bumping, changelog generation, and workspace sync.
• templates/ - Full production starter projects (website, ecommerce, blank) scaffolded by create-payload-app.
• tools/ - Internal codegen utilities for generating types, translations, and test fixtures.
• next.config.mjs - Root Next.js configuration wrapping the docs/demo site with Payload.
• payload-types.ts - Auto-generated TypeScript interfaces for every collection, global, and block in the root config.
• turbo.json - Turborepo task graph defining build, test, lint, and type-check pipelines with caching.
• vitest.config.ts - Root Vitest configuration with workspace references for all package test suites.
• tsconfig.base.json - Shared compilerOptions (strict mode, ESNext target, path aliases) inherited by every package.

Common pitfalls and fixes

• PAYLOAD_SECRET too short or missing - Payload requires at least 32 characters; set a cryptographically random string or startup will throw.
• Missing withPayload wrapper in next.config.mjs - Without it, Webpack/Turbopack cannot resolve Payload's internal aliases and you get Module not found errors; always wrap your config.
• payload generate:types not re-run after schema changes - Stale payload-types.ts causes TypeScript errors on collection fields; add npx payload generate:types to your postinstall script.
• sharp not installed for image uploads - Payload's image resize pipeline hard-requires sharp; install it explicitly (npm install sharp) and ensure it is not in devDependencies.
• Cookie SameSite issues in development - Auth cookies require NEXT_PUBLIC_SERVER_URL to match the actual origin exactly (including port); mismatches silently drop cookies and useAuth always returns user: null.
• ESM/CJS interop with non-Next.js hosts (Astro, Express) - Import the config via the named config export from your payload/src/index.ts barrel and pass it to getPayload({ config }); do not import payload.config.ts directly as a default in CJS contexts without a bundler.

Vibe-coding prompt template

I have purchased the Payload CMS source block. The source code is in the `source/` directory.
A full integration guide is in `source/USAGE.md`. The upstream package is `user@example.com`.

Please help me integrate Payload CMS into my existing Next.js 15 project step by step:

1. Read `source/USAGE.md` completely before starting.
2. Install all required dependencies listed in the "Required dependencies" section.
3. Create `payload.config.ts` at my project root using my existing database connection string in `.env`.
4. Add the Payload Next.js plugin to my `next.config.mjs`.
5. Scaffold the required API and admin routes under `app/(payload)/`.
6. Copy the auth provider pattern from `source/examples/auth/src/app/(app)/_providers/Auth/` and wire it into my root layout.
7. Generate TypeScript types with `npx payload generate:types`.
8. Show me a working server component that queries my first collection using the local API.

Use only the real exports and file paths shown in `source/USAGE.md`. Do not invent APIs.
Ask me before making any changes to files outside `app/` and `payload.config.ts`.

License and credit

Payload CMS is released under the MIT License (see source/LICENSE.md). The upstream project is maintained by the Payload team at https://github.com/payloadcms/payload and published on npm as payload. Commercial templates and cloud hosting are available at payloadcms.com.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.