Installation

Software Requirements

Payload requires the following software:

• Yarn or NPM
• NodeJS version 10+
• A Mongo Database

To quickly scaffold a new Payload app in the fastest way possible, you can use create-payload-app. To do so, run the following command:

npx create-payload-app

Then just follow the prompts! You can choose between a TypeScript project, which is fully supported by Payload, or a JavaScript project. You'll get set up with a new folder and a functioning Payload app inside.

Adding Payload to either a new or existing app is super straightforward. To add to an existing Node + Express app, just run npm install --save --legacy-peer-deps payload. Or, to start a new project from scratch, run npm init and then npm install --save --legacy-peer-deps payload express.

From there, the first step is writing a baseline config. Create a new payload.config.js in the root of your project. The simplest config contains the following:

import { buildConfig } from 'payload/config';

export default buildConfig({
  // By default, Payload will boot up normally
  // and you will be provided with a base `User` collection.
  // But, here is where you define how you'd like Payload to work!
});

Write the above code into your newly created config file. This baseline config will automatically provide you with a default User collection. For more information about users and authentication, including how to provide your own user config, jump to the Authentication section.

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.

Now that you've got a baseline Payload config, it's time to initialize Payload. It requires an Express server that you provide, so if you're not familiar with how to set up a baseline Express server, please read up on exactly what Express is and why to use it. Express' own Documentation is a good place to start. Otherwise, follow along below for how to build your own Express server to use with Payload.

1. Run npm install --save --legacy-peer-deps express if you have not done so already
2. Create a new server.js file in the root folder of your app
3. Add the following code to server.js:

const express = require('express');

const app = express();

app.listen(3000, async () => {
    console.log('Express is now listening for incoming connections on port 3000.')
});

This server doesn't do anything just yet. But, after you have this in place, we can initialize Payload via its init() method, which accepts a small set of arguments to tell it how to operate. For a full list of init arguments, please consult the main configuration docs.

To initialize Payload, update your server.js file to reflect the following code:

const express = require('express');
const payload = require('payload');

const app = express();

payload.init({
  secret: 'SECRET_KEY',
  mongoURL: 'mongodb://localhost/payload',
  express: app,
})

app.listen(3000, async () => {
    console.log('Express is now listening for incoming connections on port 3000.')
});

Here is a list of all properties available to pass through payload.init:

express

Required. This is your Express app as shown above. Payload will tie into your existing app and scope all of its functionalities to sub-routers. By default, Payload will add an /admin router and an /api router, but you can customize these paths.

secret

Required. This is a secure string that will be used to authenticate with Payload. It can be random but should be at least 14 characters and be very difficult to guess. Often, it's smart to store this value in an env and set different values for each of your environments (local, stage, prod, etc). The dotenv package is very handy and works well alongside of Payload.

mongoURL

Required. This is a fully qualified MongoDB connection string that points to your Mongo database. If you don't have Mongo installed locally, you can follow these steps for Mac OSX and these steps for Windows 10. If you want to use a local database and you know you have MongoDB installed locally, a typical connection string will look like this:

mongodb://localhost/payload

In contrast to running Mongo locally, a popular option is to sign up for a free MongoDB Atlas account, which is a fully hosted and cloud-based installation of Mongo that you don't need to ever worry about.

mongoOptions

Customize Mongo connection options. Payload will connect to your MongoDB database using default options which you can override and extend to include all the options available to mongoose.

email

An object used to configure SMTP. Read more.

local

A boolean that when set to true tells Payload to start in local-only mode which will bypass setting up API routes. When set to true, express is not required. This is useful when running scripts that need to use Payload's local-api.

loggerOptions

Specify options for the built-in Pino logger that Payload uses for internal logging. See Pino Docs for more info on what is available.

onInit

A function that is called immediately following startup that receives the Payload instance as it's only argument.

After you've gotten this far, it's time to boot up Payload. At the command line, run npm install and then node server.js in your application's folder to start up your app and initialize Payload.

After it starts, you can go to http://localhost:3000/admin to create your first Payload user!