Installation

Payload requires the following software:

• Any JavaScript package manager (Yarn, NPM, or pnpm)
• Node.js version 16+
• Any compatible database (MongoDB or Postgres)

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:

Then just follow the prompts! You'll get set up with a new folder and a functioning Payload app inside.

Adding Payload to either a new or existing TypeScript + Express app is super straightforward. To add to an existing app, just run npm install --save --legacy-peer-deps payload.

From there, the first step is writing a baseline config. Create a new payload.config.ts in your project's /src directory (or whatever your root TS dir is). The simplest config contains the following:

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.ts file in the root directory of your app
3. Add the following code to server.ts:

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

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

A quick reminder: in this configuration, we're making use of environmental variables, process.env.PAYLOAD_SECRET. Often, it's smart to store these values in an .env file at the root of your directory 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. A typical .env file will look like this:

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

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.

Payload uses this secret key to generate secure user tokens (JWT). Behind the scenes, we do not use your secret key to encrypt directly - instead, we first take the secret key and create an encrypted string using the SHA-256 hash function. Then, we reduce the encrypted string to its first 32 characters. This final value is what Payload uses for encryption.

Allows you to pass your config directly to the onInit function. The config passed here should match the payload.config file.

A boolean that disables running your onInit function when Payload starts up.

A boolean that disables the database connection when Payload starts up.

An object used to configure SMTP. Read more.

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.

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.

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

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

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. Start your project in your application's folder to get going.

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

Looking to deploy Payload with Docker? New projects with create-payload-app come with a Dockerfile and docker-compose.yml file ready to go. Examples of these files can be seen in our Deployment docs.