The Payload Config

Payload is a config-based, code-first CMS and application framework. The Payload config is central to everything that Payload does. It scaffolds the data that Payload stores as well as maintains custom React components, hook logic, custom validations, and much more. The config itself and all of its dependencies are run through Babel, so you can take full advantage of newer JavaScript features and even directly import React components containing JSX.

Also, because the Payload source code is fully written in TypeScript, its configs are strongly typed—meaning that even if you aren't using TypeScript to build your project, your IDE (such as VSCode) may still provide helpful information like type-ahead suggestions while you write your config.


serverURLA required string used to define the absolute URL of your app including the protocol, for example https://' No paths allowed, only protocol, domain and (optionally) port
collectionsAn array of all Collections that Payload will manage. To read more about how to define your collection configs, click here.
globalsAn array of all Globals that Payload will manage. For more on Globals and their configs, click here.
adminBase Payload admin configuration. Specify custom components, control metadata, set the Admin user collection, and more.
localizationOpt-in and control how Payload handles the translation of your content into multiple locales. More
graphQLManage GraphQL-specific functionality here. Define your own queries and mutations, manage query complexity limits, and more.
cookiePrefixA string that will be prefixed to all cookies that Payload sets.
corsEither a whitelist array of URLS to allow CORS requests from, or a wildcard string ('*') to accept incoming requests from any domain.
csrfA whitelist array of URLs to allow Payload cookies to be accepted from as a form of CSRF protection. More
defaultDepthIf a user does not specify depth while requesting a resource, this depth will be used. More
maxDepthThe maximum allowed depth to be permitted application-wide. This setting helps prevent against malicious queries. Defaults to 10.
uploadBase Payload upload configuration. More.
routesControl the routing structure that Payload binds itself to. Specify admin, api, graphQL, and graphQLPlayground.
emailBase email settings to allow Payload to generate email such as Forgot Password requests and other requirements. More
expressExpress-specific middleware options such as compression and JSON parsing. More.
debugEnable to expose more detailed error information.
rateLimitControl IP-based rate limiting for all Payload resources. Used to prevent DDoS attacks and more.
hooksTap into Payload-wide hooks. More
pluginsAn array of Payload plugins. More

Simple example

import { buildConfig } from 'payload/config';
const config = buildConfig({
serverURL: 'http://localhost:3000',
collections: [
slug: 'pages',
fields: [
name: 'title',
type: 'text',
required: true,
name: 'content',
type: 'richText',
required: true,
globals: [
slug: 'header',
fields: [
name: 'nav',
type: 'array',
fields: [
name: 'page',
type: 'relationship',
relationTo: 'pages',
export default config;

Full example config

You can see a full example config in the Payload source code on GitHub.

Using environment variables in your config

We suggest using the dotenv package to handle environment variables alongside of Payload. All that's necessary to do is to require the package as high up in your application as possible (for example, at the top of your server.js file), and ensure that it can find an .env file that you create.

Add this line to the top of your server:

// ...
// the rest of your `server.js` file goes here

Here is an example project structure w/ dotenv and an .env file:

---- .env
---- package.json
---- payload.config.js
---- server.js

Customizing & overriding the config location

By default, the Payload config must be in the root of your current working directory and named either payload.config.js or payload.config.ts if you're using TypeScript.

But, you can specify where your Payload config is located as well as what it's named by using the environment variable PAYLOAD_CONFIG_PATH. The path you provide via this environment variable can either be absolute or relative to your current working directory.

Example in package.json:

"scripts": {
"dev": "PAYLOAD_CONFIG_PATH=path/to/custom-config.js node server.js",

Developing within the Config

The Payload config itself, as well as all files that it requires or imports, are run through Babel. TypeScript and all common ES6 features are fully supported. To see the Babel config that is used to parse Payload configs, check out the Payload source code here.

Payload comes with isomorphic-fetch installed which means that even in Node, you can use the fetch API just as you would within the browser. No need to import axios or similar, unless you want to!

Re-using the Payload babel.config.js

If for any reason you need to re-use the built-in Payload babel.config.js, you can do so by importing it as follows:

import { config } from 'payload/babel';


You can import collection types as follows:

import { Config } from 'payload/config';
// This is the type used for an incoming Payload config.
// Only the bare minimum properties are marked as required.
import { SanitizedConfig } from 'payload/config';
// This is the type used after an incoming Payload config is fully sanitized.
// If you are building a plugin, you might benefit from this type,
// as plugins interact will fully defaulted, sanitized, and validated
// Payload configs.

Collection Configs