---
title: "PayloadCMS — Installation"
aliases: [payload-install, payload-setup, create-payload-app]
tags: [payloadcms, installation, nextjs, setup, getting-started]
sources: [getting-started__installation.md]
created: 2026-05-15
updated: 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)

```bash
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

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

Install **one** database adapter:

```bash
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](https://github.com/payloadcms/payload/tree/main/templates/blank/src/app/%28payload%29):

```
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

```js
// 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:

```ts
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`:

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

### 5. Start the app

```bash
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|Payload Config — Overview]] — full `buildConfig` options
- [[wiki/payloadcms/database-overview|Database — Overview]] — adapter selection guide
- [[wiki/payloadcms/database-postgres|Database — Postgres]] — postgresAdapter setup
- [[wiki/payloadcms/database-mongodb|Database — MongoDB]] — mongooseAdapter setup
- [[wiki/payloadcms/getting-started|PayloadCMS — Getting Started]] — what Payload is
- [[wiki/payloadcms/concepts-overview|Core Concepts]] — Collections, Globals, Fields

---

## Sources

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