How to Set Up Payload CMS v4 with Next.js 16: A Complete Getting Started Guide

Payload CMS v4 is currently in active beta and represents a major leap forward for the Next.js-native CMS ecosystem. With a redesigned admin UI, TanStack Start support, and deep Next.js 16 integration, now is the perfect time to get familiar with the new setup process. This guide walks you through everything from installation to your first deployed project.

Prerequisites

Node.js 24.22.1 or higher (required for Payload CMS v4)
A package manager: npm, yarn, or pnpm
Basic familiarity with Next.js and TypeScript
A MongoDB Atlas account or PostgreSQL database

Step 1: Create a New Payload + Next.js 16 Project

The fastest way to get started is using the official create-payload-app CLI, which scaffolds a full Next.js 16 + Payload v4 project in seconds:

npx create-payload-app@beta my-payload-app
cd my-payload-app

During setup, you’ll be prompted to choose your database adapter (MongoDB or PostgreSQL) and a starter template. For this guide, we’ll use the blank template with MongoDB.

Step 2: Configure Your Environment Variables

Rename the .env.example file to .env and fill in your values:

# .env
PAYLOAD_SECRET=your-super-secret-key-here
DATABASE_URI=mongodb+srv://username:password@cluster.mongodb.net/my-payload-db
NEXT_PUBLIC_SERVER_URL=http://localhost:3000

Important: The PAYLOAD_SECRET should be a long, random string. You can generate one with openssl rand -hex 32.

Step 3: Understand the Project Structure

Payload v4 lives entirely inside your Next.js app. Here’s the key structure:

my-payload-app/
├── src/
│   ├── app/
│   │   ├── (payload)/          # Payload admin routes
│   │   │   ├── admin/[[...segments]]/
│   │   │   └── api/[...slug]/
│   │   └── (frontend)/         # Your public-facing pages
│   ├── collections/            # Your content collections
│   └── payload.config.ts        # Main Payload configuration
├── .env
└── next.config.ts

Step 4: Create Your First Collection

Collections define your content types. Create a Posts collection at src/collections/Posts.ts:

import type { CollectionConfig } from 'payload'

export const Posts: CollectionConfig = {
  slug: 'posts',
  admin: {
    useAsTitle: 'title',
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
    },
    {
      name: 'content',
      type: 'richText',
    },
    {
      name: 'publishedAt',
      type: 'date',
    },
    {
      name: 'status',
      type: 'select',
      options: ['draft', 'published'],
      defaultValue: 'draft',
    },
  ],
}

Step 5: Register the Collection in payload.config.ts

Open src/payload.config.ts and add your new collection:

import { buildConfig } from 'payload'
import { mongooseAdapter } from '@payloadcms/db-mongodb'
import { lexicalEditor } from '@payloadcms/richtext-lexical'
import { Posts } from './ collections/Posts'

export default buildConfig({
  editor: lexicalEditor(),
  collections: [Posts],
  secret: process.env.PAYLOAD_SECRET || '',
  db: mongooseAdapter({
    url: process.env.DATABASE_URI || '',
  }),
  typescript: {
    outputFile: path.resolve(dirname, 'payload-types.ts'),
  },
})

Step 6: Run the Development Server

Start your development server and access the Payload admin panel:

npm run dev

Navigate to http://localhost:3000/admin to create your first admin user and explore the redesigned Payload v4 admin UI. You’ll immediately notice the improved accessibility and performance improvements introduced in v4.0.0-beta.4.

Step 7: Query Your Content in Next.js Pages

One of Payload v4’s biggest advantages is the Local API — query your CMS data directly in React Server Components without any HTTP overhead:

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

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

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

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

Step 8: Enable Draft Preview

Payload v4 has built-in draft preview support. Add the versions config to your collection and enable Next.js Draft Mode for a seamless editorial preview experience — no extra setup required.

Step 9: Deploy Your Project

Since Payload v4 Cloud is currently paused for new projects (following the Figma acquisition), self-hosting is the recommended path. Popular options include:

Vercel — Deploy the Next.js app; connect your MongoDB Atlas or Neon PostgreSQL database
Railway — Full-stack deployment with built-in PostgreSQL
Render — Docker-based deployment for full control

Run npm run build locally first to catch any TypeScript or build errors before deploying.

Key Takeaways

Payload CMS v4 with Next.js 16 is a powerful, developer-first stack that gives you full ownership of your content and codebase. The Local API eliminates the overhead of REST or GraphQL calls for server-side rendering, and the new admin UI makes content management a pleasure. While v4 is still in beta, it’s stable enough to start building with today — just pin your version and watch the changelog.

Hashtags: #PayloadCMS #NextJS #WebDevelopment #HeadlessCMS #TypeScript #ReactJS #JavaScript #FullStack

Resources: