obsidian/wiki/payloadcms/installation.md

title	aliases	tags	sources	created	updated
PayloadCMS — Installation	payload-install payload-setup create-payload-app	payloadcms installation nextjs setup getting-started	getting-started__installation.md	2026-05-15	2026-05-15

Requirements

• Node.js 24.15.0+
• Next.js 16.2.6+ (not all 15/16 releases are compatible — verify exact version)
• Package manager: pnpm (preferred), npm, or yarn 2+. Yarn 1.x is not supported
• Database: MongoDB, Postgres, or SQLite

cacheComponents in Next.js can be enabled alongside Payload without admin panel errors, but full compatibility is not guaranteed.

---

Option A — Quickstart (new project)

npx create-payload-app

Follow prompts → get a working Payload app in a new folder.

---

Option B — Add to existing Next.js app

1. Install packages

pnpm i payload @payloadcms/next
# Optional but common:
pnpm i @payloadcms/richtext-lexical sharp graphql

Install one database adapter:

pnpm i @payloadcms/db-mongodb   # MongoDB
pnpm i @payloadcms/db-postgres  # Postgres
pnpm i @payloadcms/db-sqlite    # SQLite

npm users: may need npm i --legacy-peer-deps

2. Copy Payload files into /app

Copy the (payload) route group from the Blank Template:

app/
├─ (payload)/   ← Payload files (never edit these)
└─ (my-app)/    ← Your frontend (rename freely: (frontend), (app), etc.)

These files are static — they import from @payloadcms/next and never need to change.

3. Add withPayload to Next.js config

// next.config.mjs  (must be ESM)
import { withPayload } from '@payloadcms/next/withPayload'

const nextConfig = {
  // your config
}

export default withPayload(nextConfig)

Make the config ESM: either add "type": "module" to package.json or rename to .mjs.

4. Create payload.config.ts

Minimal config at repo root:

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

export default buildConfig({
  editor: lexicalEditor(),
  collections: [],
  secret: process.env.PAYLOAD_SECRET || '',
  db: mongooseAdapter({
    url: process.env.DATABASE_URL || '',
  }),
  sharp,
})

Add the path alias to tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@payload-config": ["./payload.config.ts"]
    }
  }
}

5. Start the app

pnpm dev

Admin panel available at http://localhost:3000/admin.

---

Key Takeaways

• Use npx create-payload-app for new projects — fastest path
• Payload lives entirely inside Next.js /app/(payload)/ — static files, never edit
• withPayload in next.config is mandatory and must be ESM
• @payload-config tsconfig path alias is required for Payload to find the config
• sharp is optional — only needed for image resizing/cropping
• graphql package is optional — only if using GraphQL API
• Yarn 1.x is explicitly unsupported; use pnpm, npm, or yarn 2+

---

Related

• wiki/payloadcms/configuration — full buildConfig options
• wiki/payloadcms/database-overview — adapter selection guide
• wiki/payloadcms/database-postgres — postgresAdapter setup
• wiki/payloadcms/database-mongodb — mongooseAdapter setup
• wiki/payloadcms/getting-started — what Payload is
• wiki/payloadcms/concepts-overview — Collections, Globals, Fields

---

Sources

• raw/getting-started__installation.md
• https://payloadcms.com/docs/getting-started/installation