174 lines
7.3 KiB
Plaintext
174 lines
7.3 KiB
Plaintext
---
|
|
title: Installation
|
|
label: Installation
|
|
order: 30
|
|
desc: To quickly get started with Payload, simply run npx create-payload-app or install from scratch.
|
|
keywords: documentation, getting started, guide, Content Management System, cms, headless, javascript, node, react, nextjs
|
|
---
|
|
|
|
## Software Requirements
|
|
|
|
Payload requires the following software:
|
|
|
|
- Any JavaScript package manager (Yarn, NPM, or pnpm - pnpm is preferred)
|
|
- Node.js version 20.9.0+
|
|
- Any [compatible database](/docs/database/overview) (MongoDB or Postgres)
|
|
|
|
<Banner type="warning">
|
|
Before proceeding any further, please ensure that you have the above requirements met.
|
|
</Banner>
|
|
|
|
## 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@beta
|
|
```
|
|
|
|
Then just follow the prompts! You'll get set up with a new folder and a functioning Payload app inside.
|
|
|
|
## 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@beta` 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.
|
|
|
|
#### 1 - install the relevant packages
|
|
|
|
First, you'll want to add the required Payload packages to your project and can do so by running the command below (swap out `pnpm` for your package manager). Note that if you are using NPM, you might need to install using legacy peer deps (`npm i --legacy-peer-deps`).
|
|
|
|
```
|
|
pnpm i payload@beta @payloadcms/next@beta @payloadcms/richtext-lexical@beta sharp graphql
|
|
```
|
|
|
|
You'll also need to install the database adapter that you'd like to use. You have the option of Postgres (`@payloadcms/db-postgres`) or MongoDB (`@payloadcms/db-mongodb`).
|
|
|
|
#### 2 - copy Payload files into your Next.js 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.
|
|
|
|
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 Payload admin UI.
|
|
|
|
You can copy the Payload `/app` folder files from the Payload blank template on GitHub:
|
|
|
|
```
|
|
https://github.com/payloadcms/payload/tree/beta/templates/blank-3.0/src/app/(payload)
|
|
```
|
|
|
|
Notice how the Payload files are all kept within the `(payload)` [Route Group](https://nextjs.org/docs/app/building-your-application/routing/route-groups)? That's so that the Payload admin UI can have its own separate [Root Layout](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#root-layout-required) which will allow it to not interfere whatsoever with an existing Next.js app if you have one.
|
|
|
|
<Banner type="warning">
|
|
You may need to copy all of your existing frontend files, including your existing root layout, into its own newly created route group.
|
|
</Banner>
|
|
|
|
Once you have the required Payload files in place in your `/app` folder, you should have something like this:
|
|
|
|
```
|
|
/app
|
|
-- (payload) // This is the Payload route group
|
|
-- layout.tsx // Payload's root layout
|
|
-- admin // The Payload admin UI
|
|
-- api // Payload's REST / GraphQL handlers
|
|
-- custom.scss // Define custom SCSS for the Payload admin here
|
|
-- (my-app) // this is where your existing app goes
|
|
-- layout.tsx // move your existing root layout here
|
|
-- page.tsx // your existing home page
|
|
-- ...etc // whatever else you have
|
|
```
|
|
|
|
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. [Check out the Admin documentation](/docs/beta/admin/overview) for more information.
|
|
|
|
#### 3 - add the Payload plugin to your Next.js config
|
|
|
|
Payload has a plugin that it uses to ensure Next.js compatibility with some of the packages Payload relies on, like `mongodb` or `drizzle-kit`.
|
|
|
|
You need to import the `withPayload` plugin in your `next.config.js` file and wrap your config with it.
|
|
|
|
Here's an example of what your Next.js config should look like after you've imported the Payload plugin:
|
|
|
|
```js
|
|
import { withPayload } from '@payloadcms/next/withPayload'
|
|
|
|
/** @type {import('next').NextConfig} */
|
|
const nextConfig = {
|
|
// Your Next.js config here
|
|
experimental: {
|
|
reactCompiler: false
|
|
}
|
|
}
|
|
|
|
// 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 it, 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
|
|
|
|
Finally, you need to create a barebones Payload config.
|
|
|
|
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:
|
|
|
|
```ts
|
|
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_URI || '',
|
|
}),
|
|
|
|
// 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](/docs/configuration/overview).
|
|
|
|
Once you have your config created, update your `tsconfig` to include a `path` that points to your config:
|
|
|
|
```json
|
|
{
|
|
"compilerOptions": {
|
|
"paths": {
|
|
"@payload-config": [
|
|
"./payload.config.ts"
|
|
]
|
|
}
|
|
},
|
|
}
|
|
```
|
|
|
|
#### 5 - fire it up!
|
|
|
|
After you've gotten this far, 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!
|