Getting Started

Tech Stack

NextJS version ^15.0.0 (App Router)
PayloadCMS version ^3.0.0

Installation

If you want to start a fresh NextJS project with PayloadCMS, you can jump to this section. Otherwise, you can integrate PayloadCMS to your existing NextJS project by following the steps below.

Integrate PayloadCMS to existing NextJS project

Pre-requirement

PayloadCMS doesn’t support a root layout inside app directory. So, if your files is directly on app directory, you need to move it inside a sub-folder.

If your project structure look like this:

Directorypublic/
- …
Directorysrc
- Directoryapp
  - favicon.ico
  - globals.css
  - layout.tsx
  - page.tsx
package.json
next.config.ts

You need to move all the files inside app directory to a sub-folder, for example (landing) like this:

Directorypublic/
- …
Directorysrc
- Directoryapp
  - Directory(landing)
    favicon.ico
    globals.css
    layout.tsx
    page.tsx
    … all other files goes here
package.json
next.config.ts

These should not affect your project. Your project should still work as expected.

Install PayloadCMS

Go to your existing NextJS project folder and run the following command on your terminal:
Terminal window
```
npx create-payload-app
```

It will be automatically detected that we are have NextJS project already. Just hit Enter.

┌   create-payload-app
│
◇   ────────────────────────────────────────────╮
│                                               │
│  Welcome to Payload. Let's create a project!  │
│                                               │
├───────────────────────────────────────────────╯
│
◇   ▲ Next.js  project detected!
│
◆  Install Payload in this project?
│  ● Yes / ○ No
└

If you have encounter an error like this :

▲
│  Next Steps:
│
│  Payload does not support a top-level layout.tsx file in the app directory.
│
│  To continue:
│
│  - Create a new directory in ./src\app such as ./src\app/(app)
│  - Move all files from ./src\app into that directory
│
│  It is recommended to do this from your IDE if your app has existing file references.
│
│  Once moved, rerun the create-payload-app command again.

You might be miss the pre-requirement step. After moving all the files, re-execute the installation command.

On database selection step, choose SQLite.

◆  Select a database
│  ○ MongoDB
│  ○ PostgreSQL
│  ● SQLite
│  ○ Vercel Postgres
└

You can enter the file name for the database, or just press enter to use the default name.

│
◆  Enter SQLite connection string
│  file:./test-payloadcms.db
└

Payload requires some environment variables to run. You can create a .env file on the root of your project and add the following environment variables:
Terminal window
```
PAYLOAD_SECRET=your_secret_key
DATABASE_URI=libsql:./test-payloadcms.db
```
You can generate a secret key by running the following command on your terminal:
Terminal window
```
node -e "console.log(require('crypto').randomBytes(12).toString('hex'))"
```
Once everything set, you can run the project with the following command:
- npm
- yarn
Terminal window
npm run dev
Terminal window
yarn dev
You can access the PayloadCMS dashboard by visiting http://localhost:3000/admin on your browser.

A fresh NextJS project with PayloadCMS

Go to your desired folder and run the following command on your terminal
Terminal window
```
npx create-payload-app
```

You will be prompted to enter your project name and the template you want to use.

┌   create-payload-app
│
◇  ────────────────────────────────────────────╮
│                                               │
│  Welcome to Payload. Let's create a project!  │
│                                               │
├───────────────────────────────────────────────╯
│
◇  Project name?
│  test-payloadcms
│
◆  Choose project template
│  ● blank
│  ○ website
│  ○ plugin
└

Choose the blank template.

Then, choose sqlite as database.

◆  Select a database
│  ○ MongoDB
│  ○ PostgreSQL
│  ● SQLite
│  ○ Vercel Postgres
└

You can enter the file name for the database, or just press enter to use the default name.

│
◆  Enter SQLite connection string
│  file:./test-payloadcms.db
└

Wait until the installation is finished.

If you are not using pnpm as package manager, you might encounter an error like this:

◇  Using pnpm.
│
◐  Installing dependencies...
│
■  Error installing dependencies: Command failed with exit code 1: pnpm install
│  C:\Program Files\nodejs\node_modules\corepack\dist\lib\corepack.cjs:22373
│                throw new UsageError(`This project is configured to use ${result.spec.name} because ${result.target} has a "packageManager" field`);
│                      ^
│
│  UsageError: This project is configured to use yarn because C:\Users\user\package.json has a "packageManager" field
│      at Engine.findProjectSpec (C:\Program Files\nodejs\node_modules\corepack\dist\lib\corepack.cjs:22373:21)
│      at async Engine.executePackageManagerRequest (C:\Program Files\nodejs\node_modules\corepack\dist\lib\corepack.cjs:22404:24)
│      at async Object.runMain (C:\Program Files\nodejs\node_modules\corepack\dist\lib\corepack.cjs:23096:5) {
│    clipanion: { type: 'usage' }
│  }
│
│  Node.js v22.11.0.
■  Error installing dependencies
│

Don’t worry, you can just cd into the folder and run the installation command with your package manager.

npm
yarn

cd test-payloadcms
npm install

cd test-payloadcms
yarn

After the installation is finished, you can run the project with the following command:
- npm
- yarn
Terminal window
npm run dev
Terminal window
yarn dev
You can access the PayloadCMS dashboard by visiting http://localhost:3000/admin on your browser.