Setting up Payload CMS 3 with Next.js 16 and PostgreSQL

The Payload CMS 3 is hosted inside a Next.js app. Rather than having to deal with a separate CMS on the backend and frontend, you have all of these in your TypeScript project. In this guide, you will learn how to set up Payload CMS 3 with Next.js 16 and PostgreSQL. We will also configure the official SEO plugin and Vercel Blob storage.

There are two ways to follow this guide:

1. Use my free blank starter template for the quickest setup.
2. Create the project manually using Payload’s official project generator.

The basic template will do for starters if a basic working framework is needed. The manual process will be preferred if one wants to know how the first payload was created.

Last checked: September 2026. Payload and Next.js requirements can change, so verify the versions in the linked official documentation before starting a production project.

Prerequisites

1. Node.js 20.9.0 or newer
2. pnpm, npm or Yarn 2+
3. A PostgreSQL database
4. Basic familiarity with Next.js and TypeScript

Payload recommends pnpm, which I will use throughout this guide. You may verify the latest requirements in Payload’s official installation guide. You can install pnpm via this command:

npm install -g pnpm

Choose your setup method

Method 1: Use the free starter template

This is the easiest option if you are a beginner or are experiencing problems with the initial setup.

The starter repository provides a blank project structure with:

Next.js 16, Payload CMS 3, PostgreSQL configuration, A Payload admin panel, A Users collection, A Media collection, Payload’s SEO plugin, Vercel-Blob storage configuration, An environment-variable example, Setup instructions in the README

git clone https://github.com/Abdullah25r/nextjs-payload-starter-kit-for-beginner

cd nextjs-payload-starter-kit-for-beginner

pnpm install

A .env.example file also uploaded here with dummy placeholders. you just replace four variables with you actual ones and change it name to .env.local

If you still confuse you can follow the step by step guide line in readme.md file for each variable source. After basic setup completion run the application in development mode by using following command.

pnpm dev

Open the website: http://localhost:3000

Open the Payload admin panel: http://localhost:3000/admin

On your first visit, Payload will ask you to create the initial administrator account.

You can download my free Payload CMS and PostgreSQL starter from GitHub. The README explains where to obtain each environment variable and how to run the project.

Important: Never commit your actual .env file, database password, Payload secret or Blob token to GitHub.

If the starter works for you, you can move directly to the section explaining the project structure. If you want to build the setup yourself, continue with the manual method.

Method 2: Create the project manually

Payload provides an official command for generating a new project.

Run:

npx create-payload-app@latest

The setup will ask you to provide a project name and select the available configuration options. You may pick on your own choice which database, package manager or plugin you will use, it will automatically install all required dependencies

After installation, enter your project folder:

cd your-project-name

Start the development server:

pnpm dev

Obtain a PostgreSQL connection string from your local database or managed database provider. Add it to .env:

DATABASE_URL=your_postgresql_connection_string
PAYLOAD_SECRET=your_long_random_secret

The key thing here is that postgresAdapter gets your DATABASE_URL via its connection pool. There can be some extra configuration in the auto-generated code. Don't delete it just to make your file look like in a tutorial. Payload works using Drizzle ORM and node-postgres under its official PostgreSQL adapter. You can find the configuration options for it in the PostgreSQL adapter documentation.

Create your first admin account

Run the development server if it is not already running:

pnpm dev

Visit:

http://localhost:3000/admin

When no user exists, Payload displays a registration form for the first administrator. Enter your email address and a secure password. After registration, you will be redirected to the Payload admin dashboard.

Understand the project structure

src/

├── app/ │

├── (frontend)/

└── (payload)/

├── collections/

├── payload.config.ts

└── payload-types.ts

The frontend route group

The (frontend) route group holds your Next.js public pages and layouts and components. This is built using the regular Next.js App Router.

The Payload route group

The (payload)route group holds routes that are necessary for the admin panel and the Payload APIs. These generated routes link Payload with the Next.js application. Normally you do not have to edit them when setting up the basics.

Collections

The collections directory contains the schemas for your application’s data.

Examples include:

1. Users
2. Media
3. Posts
4. Categories
5. Products
6. Authors
7. Bookings

When you add a collection to the Payload configuration, Payload can generate its admin interface and APIs.

Add the Payload SEO plugin

Payload’s official SEO plugin lets content editors manage search metadata from the admin panel. Install it:

pnpm add @payloadcms/plugin-seo

Import seoPlugin into payload.config.ts and place it inside the plugins array. Enable it for your Posts collection and connect it to your Media collection.

Once configured, it can add: Meta title, Meta description, Meta image, Search-result preview, Metadata auto-generation

For example, your title generator can append your site name:

Article Title | Abdullah’s Blog

Add Vercel Blob storage

During local development, Payload can store uploaded files on your computer. That approach is unsuitable for many serverless deployments because local uploaded files may disappear after redeployment. For a project hosted on Vercel, you can use Payload’s official Vercel Blob adapter. Install it:

pnpm add @payloadcms/storage-vercel-blob

Before configuring the plugin, ensure that your project has an upload-enabled Media collection.

Useful official links

These are the primary official resources used in this guide:

• Payload installation documentation
• Payload PostgreSQL adapter
• Payload Local API
• Payload SEO plugin
• Payload storage adapters
• Payload database migrations
• Next.js installation documentation

Use links inside the relevant sections of the article. This final list can remain as a compact reference, but avoid linking every repeated mention of the same technology.

Outlook

Two options for getting started with Payload CMS 3 are Next.js 16 and PostgreSQL. If you want a quick start, download my free Payload CMS and PostgreSQL starter from GitHub., follow its instructions and set your own environment variables. If you want to learn the configuration process yourself, go for Payload’s official project generator.

Start with a small working structure. Once you understand how collections affect the database, admin panel and APIs together, you can gradually turn the project into a complete blog, business website or content platform.