How to Build a Full-Stack App with Payload CMS and Next.js 16

Build a Full-Stack App with Payload CMS and Next.js 16

Payload CMS and Next.js 16 are a powerhouse combination for modern full-stack web development. Payload gives you a TypeScript-native headless CMS with a built-in admin panel, while Next.js 16 delivers blazing-fast rendering, the App Router, and Turbopack. In this guide, we’ll walk through building a complete full-stack application from scratch.

Prerequisites

Node.js 20+ installed
Basic knowledge of TypeScript and React
A PostgreSQL or MongoDB database (local or cloud)

Step 1: Scaffold Your Payload + Next.js Project

The fastest way to get started is using the official create-payload-app CLI, which now scaffolds a fully integrated Next.js 16 project:

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

During setup, choose your preferred database adapter (PostgreSQL recommended for production) and select the website or blank template. The CLI will scaffold a Next.js 16 app with Payload embedded directly inside it — no separate backend server needed.

Step 2: Configure Your Database

Open payload.config.ts and configure your database adapter. For PostgreSQL:

import { postgresAdapter } from '@payloadcms/db-postgres'

export default buildConfig({
  db: postgresAdapter({
    pool: {
      connectionString: process.env.DATABASE_URI,
    },
  }),
  // ...
})

Add your DATABASE_URI to your .env file and run migrations:

npx payload migrate

Step 3: Define Your Content Collections

Collections are the heart of Payload. Define a Posts collection in 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',
    },
  ],
}

collections: [Posts],

Step 4: Access the Admin Panel

Start your development server:

npm run dev

Navigate to http://localhost:3000/admin to access the Payload admin panel. Create your first admin user and start adding content. The admin UI is fully customizable with React components.

Step 5: Fetch Content in Next.js App Router

With Payload embedded in your Next.js app, you can use the Local API for zero-latency data fetching — no HTTP requests needed:

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' },
    },
    sort: '-publishedAt',
  })

  return (
    <main>
      {posts.docs.map((post) => (
        <article key={post.id}>
          <h2>{post.title}</h2>
        </article>
      ))}
    </main>
  )
}

Step 6: Enable Draft Preview

Payload’s draft system integrates seamlessly with Next.js Draft Mode. Add a preview endpoint and configure your collection with versions: { drafts: true } to enable live preview of unpublished content directly in your frontend.

Step 7: Deploy to Production

Payload CMS v3.84+ supports deployment to any Node.js-compatible platform. Popular options include:

Vercel — Use the official Next.js adapter for edge-optimized deployments
Railway / Render — Great for full-stack Node.js apps with managed PostgreSQL
Self-hosted — Deploy to any VPS with Docker for full control

Set your environment variables (DATABASE_URI, PAYLOAD_SECRET, NEXT_PUBLIC_SERVER_URL) and run:

npm run build
npm start

Key Takeaways

Payload CMS v3.84 is fully integrated with Next.js 16 — one codebase, one deployment
The Local API eliminates network overhead for server-side data fetching
TypeScript-first design means type-safe content models from database to UI
The new create-payload-app --agent flag installs AI coding skills for Claude, Codex, and Cursor

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

Resources: