vault backup: 2026-05-15 14:27:10
This commit is contained in:
Vadym Samoilenko
parent
f86462c840
commit
82978d5b73
4 changed files with 344 additions and 1 deletions
203
raw/_processed/Installation Documentation.md
Normal file
203
raw/_processed/Installation Documentation.md
Normal file
|
|
@ -0,0 +1,203 @@
|
|||
---
|
||||
title: "Installation | Documentation"
|
||||
source: "https://payloadcms.com/docs/getting-started/installation"
|
||||
author:
|
||||
published:
|
||||
created: 2026-05-15
|
||||
description: "To quickly get started with Payload, simply run npx create-payload-app or install from scratch."
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||
## Installation
|
||||
|
||||
## [Software Requirements](https://payloadcms.com/docs/getting-started/installation#software-requirements)
|
||||
|
||||
Payload requires the following software:
|
||||
|
||||
- Any JavaScript package manager (pnpm, npm, or yarn 2+ - pnpm is preferred, yarn 1.x is not supported)
|
||||
- Node.js version 20.9.0+
|
||||
- Next.js (one of the following version ranges):
|
||||
- `15.2.9` - `15.2.x`
|
||||
- `15.3.9` - `15.3.x`
|
||||
- `15.4.11` - `15.4.x`
|
||||
- `16.2.2` +
|
||||
- Any [compatible database](https://payloadcms.com/docs/database/overview) (MongoDB, Postgres or SQLite)
|
||||
|
||||
**Important:** Before proceeding any further, please ensure that you have the above requirements met. Not all Next.js 15/16 releases are compatible — make sure you're using one of the supported version ranges listed above.
|
||||
|
||||
**Cache Components:** While Next.js `cacheComponents` can be enabled alongside Payload without causing errors in the admin panel, full compatibility is not guaranteed. See this [GitHub pull request](https://github.com/payloadcms/payload/pull/16020) for the latest status.
|
||||
|
||||
## [Quickstart with create-payload-app](https://payloadcms.com/docs/getting-started/installation#quickstart-with-create-payload-app)
|
||||
|
||||
To quickly scaffold a new Payload app in the fastest way possible, you can use [create-payload-app](https://npmjs.com/package/create-payload-app). To do so, run the following command:
|
||||
|
||||
npx create-payload-app
|
||||
|
||||
Then just follow the prompts! You'll get set up with a new folder and a functioning Payload app inside. You can then start [configuring your application](https://payloadcms.com/docs/configuration/overview).
|
||||
|
||||
## [Adding to an existing app](https://payloadcms.com/docs/getting-started/installation#adding-to-an-existing-app)
|
||||
|
||||
Adding Payload to an existing Next.js app is super straightforward. You can either run the `npx create-payload-app` command inside your Next.js project's folder, or manually install Payload by following the steps below.
|
||||
|
||||
If you don't have a Next.js app already, but you still want to start a project from a blank Next.js app, you can create a new Next.js app using `npx create-next-app` - and then just follow the steps below to install Payload.
|
||||
|
||||
First, you'll want to add the required Payload packages to your project:
|
||||
|
||||
pnpm i payload @payloadcms/next
|
||||
|
||||
You'll also likely want to install the following optional packages:
|
||||
|
||||
- `@payloadcms/richtext-lexical` - Rich text editor (not needed if you don't use Rich Text)
|
||||
- `sharp` - Image resizing, cropping, and focal point support (only needed if you use [Upload](https://payloadcms.com/docs/upload/overview) collections with image manipulation)
|
||||
- `graphql` - Only needed if you want to use the [GraphQL API](https://payloadcms.com/docs/graphql/overview)
|
||||
|
||||
pnpm i @payloadcms/richtext-lexical sharp graphql
|
||||
|
||||
**Note:** Swap out `pnpm` for your package manager. If you are using npm, you might need to install using legacy peer deps: `npm i --legacy-peer-deps`.
|
||||
|
||||
Next, install a [Database Adapter](https://payloadcms.com/docs/database/overview). Payload requires a Database Adapter to establish a database connection. Payload works with all types of databases, but the most common are MongoDB and Postgres.
|
||||
|
||||
To install a Database Adapter, you can run **one** of the following commands:
|
||||
|
||||
- To install the [MongoDB Adapter](https://payloadcms.com/docs/database/mongodb), run:
|
||||
|
||||
pnpm i @payloadcms/db-mongodb
|
||||
|
||||
- To install the [Postgres Adapter](https://payloadcms.com/docs/database/postgres), run:
|
||||
|
||||
pnpm i @payloadcms/db-postgres
|
||||
|
||||
- To install the [SQLite Adapter](https://payloadcms.com/docs/database/sqlite), run:
|
||||
|
||||
pnpm i @payloadcms/db-sqlite
|
||||
|
||||
**Note:** New [Database Adapters](https://payloadcms.com/docs/database/overview) are becoming available every day. Check the docs for the most up-to-date list of what's available.
|
||||
|
||||
#### [2\. Copy Payload files into your Next.js app folder](https://payloadcms.com/docs/getting-started/installation#2-copy-payload-files-into-your-nextjs-app-folder)
|
||||
|
||||
Payload installs directly in your Next.js `/app` folder, and you'll need to place some files into that folder for Payload to run. You can copy these files from the [Blank Template](https://github.com/payloadcms/payload/tree/3.x/templates/blank/src/app/%28payload%29) on GitHub. Once you have the required Payload files in place in your `/app` folder, you should have something like this:
|
||||
|
||||
app/
|
||||
|
||||
├─ (payload)/
|
||||
|
||||
├── // Payload files
|
||||
|
||||
├─ (my-app)/
|
||||
|
||||
├── // Your app files
|
||||
|
||||
*For an exact reference of the* `*(payload)*` *directory, see* [*Project Structure*](https://payloadcms.com/docs/admin/overview#project-structure)*.*
|
||||
|
||||
You may need to copy all of your existing frontend files, including your existing root layout, into its own newly created [Route Group](https://nextjs.org/docs/app/building-your-application/routing/route-groups), i.e. `(my-app)`.
|
||||
|
||||
The files that Payload needs to have in your `/app` folder do not regenerate, and will never change. Once you slot them in, you never have to revisit them. They are not meant to be edited and simply import Payload dependencies from `@payloadcms/next` for the REST / GraphQL API and Admin Panel.
|
||||
|
||||
You can name the `(my-app)` folder anything you want. The name does not matter and will just be used to clarify your directory structure for yourself. Common names might be `(frontend)`, `(app)`, or similar. [More details](https://payloadcms.com/docs/admin/overview).
|
||||
|
||||
#### [3\. Add the Payload Plugin to your Next.js config](https://payloadcms.com/docs/getting-started/installation#3-add-the-payload-plugin-to-your-nextjs-config)
|
||||
|
||||
Payload has a Next.js plugin that it uses to ensure compatibility with some of the packages Payload relies on, like `mongodb` or `drizzle-kit`.
|
||||
|
||||
To add the Payload Plugin, use `withPayload` in your `next.config.js`:
|
||||
|
||||
import { withPayload } from '@payloadcms/next/withPayload'
|
||||
|
||||
/\*\* @type {import('next').NextConfig} \*/
|
||||
|
||||
const nextConfig = {
|
||||
|
||||
// Your Next.js config here
|
||||
|
||||
}
|
||||
|
||||
// Make sure you wrap your \`nextConfig\`
|
||||
|
||||
// with the \`withPayload\` plugin
|
||||
|
||||
export default withPayload(nextConfig)
|
||||
|
||||
**Important:** Payload is a fully ESM project, and that means the `withPayload` function is an ECMAScript module.
|
||||
|
||||
To import the Payload Plugin, you need to make sure your `next.config` file is set up to use ESM.
|
||||
|
||||
You can do this in one of two ways:
|
||||
|
||||
1. Set your own project to use ESM, by adding `"type": "module"` to your `package.json` file
|
||||
2. Give your Next.js config the `.mjs` file extension
|
||||
|
||||
In either case, all `require` s and `export` s in your `next.config` file will need to be converted to `import` / `export` if they are not set up that way already.
|
||||
|
||||
#### [4\. Create a Payload Config and add it to your TypeScript config](https://payloadcms.com/docs/getting-started/installation#4-create-a-payload-config-and-add-it-to-your-typescript-config)
|
||||
|
||||
Finally, you need to create a [Payload Config](https://payloadcms.com/docs/configuration/overview). Generally the Payload Config is located at the root of your repository, or next to your `/app` folder, and is named `payload.config.ts`.
|
||||
|
||||
Here's what Payload needs at a bare minimum:
|
||||
|
||||
import sharp from 'sharp'
|
||||
|
||||
import { lexicalEditor } from '@payloadcms/richtext-lexical'
|
||||
|
||||
import { mongooseAdapter } from '@payloadcms/db-mongodb'
|
||||
|
||||
import { buildConfig } from 'payload'
|
||||
|
||||
export default buildConfig({
|
||||
|
||||
// If you'd like to use Rich Text, pass your editor here
|
||||
|
||||
editor: lexicalEditor(),
|
||||
|
||||
// Define and configure your collections in this array
|
||||
|
||||
collections: \[\],
|
||||
|
||||
// Your Payload secret - should be a complex and secure string, unguessable
|
||||
|
||||
secret: process.env.PAYLOAD\_SECRET || '',
|
||||
|
||||
// Whichever Database Adapter you're using should go here
|
||||
|
||||
// Mongoose is shown as an example, but you can also use Postgres
|
||||
|
||||
db: mongooseAdapter({
|
||||
|
||||
url: process.env.DATABASE\_URL || '',
|
||||
|
||||
}),
|
||||
|
||||
// If you want to resize images, crop, set focal point, etc.
|
||||
|
||||
// make sure to install it and pass it to the config.
|
||||
|
||||
// This is optional - if you don't need to do these things,
|
||||
|
||||
// you don't need it!
|
||||
|
||||
sharp,
|
||||
|
||||
})
|
||||
|
||||
Although this is just the bare minimum config, there are *many* more options that you can control here. To reference the full config and all of its options, [click here](https://payloadcms.com/docs/configuration/overview).
|
||||
|
||||
Once you have a Payload Config, update your `tsconfig` to include a `path` that points to it:
|
||||
|
||||
{
|
||||
|
||||
"compilerOptions": {
|
||||
|
||||
"paths": {
|
||||
|
||||
"@payload-config": \["./payload.config.ts"\]
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
#### [5\. Fire it up!](https://payloadcms.com/docs/getting-started/installation#5-fire-it-up)
|
||||
|
||||
After you've reached this point, it's time to boot up Payload. Start your project in your application's folder to get going. By default, the Next.js dev script is `pnpm dev` (or `npm run dev` if using npm).
|
||||
|
||||
After it starts, you can go to `http://localhost:3000/admin` to create your first Payload user!
|
||||
|
|
@ -20,7 +20,7 @@ This 3-hop pattern works for hundreds of articles without vector search.
|
|||
|-------|-------------|----------|
|
||||
| [[wiki/obsidian-rag/_index\|obsidian-rag/]] | Karpathy's LLM wiki method — Obsidian RAG, setup, vs true RAG | 3 |
|
||||
| [[wiki/projects-overview/_index\|projects-overview/]] | All 42 Oliver Agency projects — grouped by server (optical-web-1, optical-dev, baic, box-cli) | 1 |
|
||||
| [[wiki/tech-patterns/_index\|tech-patterns/]] | Recurring tech stacks: FastAPI, React/Vite, Next.js, Azure AD, AI, Box, One2Edit, Redis/Celery, cost-tracker, OMG API | 29 |
|
||||
| [[wiki/tech-patterns/_index\|tech-patterns/]] | Recurring tech stacks: FastAPI, React/Vite, Next.js, Azure AD, AI, Box, One2Edit, Redis/Celery, cost-tracker, OMG API, Payload CMS | 30 |
|
||||
| [[wiki/architecture/_index\|architecture/]] | Cross-cutting architectural patterns: Docker Compose, multi-agent AI, GCP timeout, RAG, hotfolder, optical-dev deploy, cost-tracker, new-project checklist, troubleshooting playbooks, ADR log, Cloud Run Jobs | 11 |
|
||||
| [[wiki/client-knowledge/_index\|client-knowledge/]] | Per-client notes for Ford, H&M, L'Oréal, Barclays, Ferrero, 3M, BAIC | 7 |
|
||||
| [[wiki/concepts/_index\|concepts/]] | Atomic knowledge extracted from Claude Code sessions | 201 |
|
||||
|
|
|
|||
|
|
@ -44,6 +44,7 @@ Recurring technology stacks used across Oliver Agency projects. Each article cov
|
|||
| [[wiki/tech-patterns/omg-api\|OMG Platform REST API]] | Oliver internal marketing ops REST API (v2) — briefs, deliverables, tasks, users; TYK gateway + X-Api-Key auth; RFC 7807 errors | Ferrero, 3M OMG Portal |
|
||||
| [[wiki/tech-patterns/omg-api 2\|OMG Platform REST API]] | REST API for the **OMG marketing operations platform** (Oliver internal). Manages briefs, deliverabl | raw/Scalar API Reference.md |
|
||||
| [[wiki/tech-patterns/docker-compose-systemd-auto-restart\|Docker Compose Auto-Restart with Systemd Service]] | When a Docker Compose application (like a multi-container stack) needs to automatically restart afte | — |
|
||||
| [[wiki/tech-patterns/payload-cms-installation\|Payload CMS — Installation & Setup]] | TypeScript-first headless CMS running inside Next.js App Router — install, `withPayload`, `payload.config.ts`, DB adapters | — |
|
||||
|
||||
## Quick Decision Guide
|
||||
|
||||
|
|
|
|||
139
wiki/tech-patterns/payload-cms-installation.md
Normal file
139
wiki/tech-patterns/payload-cms-installation.md
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
---
|
||||
title: "Payload CMS — Installation & Setup"
|
||||
aliases: [payload-cms, payloadcms-install, payload-nextjs]
|
||||
tags: [payload-cms, nextjs, cms, headless, typescript]
|
||||
sources: [raw/Installation Documentation.md]
|
||||
created: 2026-05-15
|
||||
updated: 2026-05-15
|
||||
---
|
||||
|
||||
## Payload CMS — Installation & Setup
|
||||
|
||||
[Payload CMS](https://payloadcms.com) is a TypeScript-first headless CMS that runs **inside** a Next.js app (App Router). No separate backend process — Payload lives in your `/app/(payload)/` route group.
|
||||
|
||||
## Requirements
|
||||
|
||||
| Requirement | Version |
|
||||
|-------------|---------|
|
||||
| Node.js | 20.9.0+ |
|
||||
| Next.js | `15.2.9–15.2.x` / `15.3.9–15.3.x` / `15.4.11–15.4.x` / `16.2.2+` |
|
||||
| Package manager | pnpm (preferred), npm, yarn 2+ (yarn 1.x **not supported**) |
|
||||
| Database | MongoDB, Postgres, or SQLite |
|
||||
|
||||
> **Not all Next.js 15/16 patch releases are compatible** — use only the version ranges above.
|
||||
|
||||
## Quickstart (new project)
|
||||
|
||||
```bash
|
||||
npx create-payload-app
|
||||
```
|
||||
|
||||
Follow the prompts — you get a working Payload app in a new folder.
|
||||
|
||||
## Add to Existing Next.js App
|
||||
|
||||
### 1. Install packages
|
||||
|
||||
```bash
|
||||
pnpm i payload @payloadcms/next
|
||||
|
||||
# Optional but common:
|
||||
pnpm i @payloadcms/richtext-lexical # Rich text editor
|
||||
pnpm i sharp # Image resize/crop/focal point
|
||||
pnpm i graphql # Only if using GraphQL API
|
||||
```
|
||||
|
||||
**Database adapter — pick one:**
|
||||
|
||||
```bash
|
||||
pnpm i @payloadcms/db-mongodb # MongoDB
|
||||
pnpm i @payloadcms/db-postgres # Postgres
|
||||
pnpm i @payloadcms/db-sqlite # SQLite
|
||||
```
|
||||
|
||||
> npm users: `npm i --legacy-peer-deps`
|
||||
|
||||
### 2. Copy Payload files into `/app`
|
||||
|
||||
Copy the `(payload)` route group from [Blank Template](https://github.com/payloadcms/payload/tree/3.x/templates/blank/src/app/%28payload%29):
|
||||
|
||||
```
|
||||
app/
|
||||
├── (payload)/ ← Payload admin + API routes (never edit these)
|
||||
└── (my-app)/ ← Your existing frontend (rename freely)
|
||||
```
|
||||
|
||||
Move existing frontend files into a new route group (e.g. `(frontend)`). Payload files import from `@payloadcms/next` — set once, never revisited.
|
||||
|
||||
### 3. Wrap Next.js config with `withPayload`
|
||||
|
||||
```js
|
||||
// next.config.mjs ← must be ESM (.mjs or "type":"module" in package.json)
|
||||
import { withPayload } from '@payloadcms/next/withPayload'
|
||||
|
||||
const nextConfig = {
|
||||
// your config
|
||||
}
|
||||
|
||||
export default withPayload(nextConfig)
|
||||
```
|
||||
|
||||
> Payload is fully ESM — `require()` won't work. Use `.mjs` extension or set `"type": "module"`.
|
||||
|
||||
### 4. Create `payload.config.ts`
|
||||
|
||||
```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,
|
||||
})
|
||||
```
|
||||
|
||||
Register the config path in `tsconfig.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"paths": {
|
||||
"@payload-config": ["./payload.config.ts"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Start & create first user
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
# → http://localhost:3000/admin
|
||||
```
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
- Payload runs **inside Next.js** — no separate server; admin panel at `/admin`
|
||||
- Only specific Next.js patch versions are compatible — check the list before upgrading
|
||||
- `(payload)` route group files are **never edited** — they're boilerplate from the template
|
||||
- `withPayload` in `next.config` must be ESM — use `.mjs` or `"type":"module"`
|
||||
- `PAYLOAD_SECRET` must be a strong random string (used to sign tokens)
|
||||
- `sharp` is optional — only needed for image manipulation in Upload collections
|
||||
- `@payloadcms/richtext-lexical` is optional — only needed if using Rich Text fields
|
||||
|
||||
## Related
|
||||
|
||||
- [[wiki/tech-patterns/nextjs-fastapi-fullstack|Next.js + FastAPI Fullstack]] — alternative when you need a separate Python backend
|
||||
- [[wiki/tech-patterns/react-vite-typescript|React + Vite + TypeScript]] — SPA alternative without SSR/CMS
|
||||
- [[wiki/tech-patterns/azure-ad-msal-auth|Azure AD / MSAL Auth]] — if Payload needs SSO instead of built-in auth
|
||||
|
||||
## Sources
|
||||
|
||||
- `raw/Installation Documentation.md` — clipped from https://payloadcms.com/docs/getting-started/installation
|
||||
Loading…
Add table
Reference in a new issue