Payload Concepts

Payload is based around a small and intuitive set of concepts. Before starting to work with Payload, it's a good idea to familiarize yourself with the following:

Config

By default, the Payload config lives in the root folder of your code and is named payload.config.js (payload.config.ts if you're using TypeScript), but you can customize its name and where you store it. You can write full functions and even full React components right into your config.

Collections

Collections define the shape of your data as well as all functionalities attached to that data. They will contain one or many "documents", all corresponding with the same fields and functionalities that you define.

They can represent anything you can store in a database - for example - pages, posts, users, people, orders, categories, events, customers, transactions, and anything else your app needs.

Globals

Globals are in many ways similar to Collections, but there is only ever one instance of a Global, whereas Collections can contain many documents.

Fields

Payload comes with many different field types that give you a ton of flexibility while designing your API. Each Field type has its own potential properties that allow you to customize how they work.

Hooks

Hooks are an extremely powerful concept and are central to extending and customizing your app. Payload provides a wide variety of hooks which you can utilize. For example, imagine if you'd like to send an email every time a document is created in your Orders collection. To do so, you can add an afterChange hook function to your Orders collection that receives the Order data and allows you to send an email accordingly.

There are many more potential reasons to use Hooks. For more, visit the Hooks documentation.

Access Control

Access Control is extremely powerful but easy and intuitive to manage. You can easily define your own full-blown RBAC (role-based access control) or any other access control pattern that your scenario requires. No conventions or structure is forced on you whatsoever.

For more, visit the Access Control documentation.

Depth

You can specify population depth via query parameter in the REST API and by an option in the local API. Depth has no effect in the GraphQL API, because there, depth is based on the shape of your queries. It is also possible to limit the depth for specific relation and upload fields using the maxDepth property in your configuration. For example, let's look at the following Collections: departments, users, posts

1
// type: 'relationship' fields are equal to 1 depth level
2
3
{
4
slug: 'posts',
5
fields: [
6
{
7
name: 'title',
8
type: 'text',
9
},
10
{
11
name: 'author',
12
label: 'Post Author',
13
type: 'relationship',
14
relationTo: 'users',
15
}
16
]
17
}
18
19
{
20
slug: 'users',
21
fields: [
22
{
23
name: 'email',
24
type: 'email',
25
},
26
{
27
name: 'department'
28
type: 'relationship',
29
relationTo: 'departments'
30
}
31
]
32
}
33
34
{
35
slug: 'departments',
36
fields: [
37
{
38
name: 'name'
39
type: 'text',
40
}
41
]
42
}

If you were to query the Posts endpoint at, say, http://localhost:3000/api/posts?depth=1, you will retrieve Posts with populations one level deep. This depth parameter can be thought of as N, where N is the number of levels you want to populate. To populate one level further, you would simply specify N+1 as the depth. A returned result may look like the following:

1
// ?depth=1
2
3
{
4
id: '5ae8f9bde69e394e717c8832',
5
title: 'This post sucks',
6
author: {
7
id: '5f7dd05cd50d4005f8bcab17',
8
email: 'spiderman@superheroes.gov',
9
department: '5e3ca05cd50d4005f8bdab15'
10
}
11
}

Notice how the user.author is fully populated, but user.author.department is left as a document ID? That's because the User collection counted as the first level of depth and got populated—but then prevented any further populations from taking place.

To populate user.author.department in it's entirety you could specify ?depth=2 or higher.

1
// ?depth=2
2
3
{
4
id: '5ae8f9bde69e394e717c8832',
5
title: 'This post sucks',
6
author: {
7
id: '5f7dd05cd50d4005f8bcab17',
8
email: 'spiderman@superheroes.gov',
9
department: {
10
id: '5e3ca05cd50d4005f8bdab15',
11
name: 'Marvel'
12
}
13
}
14
}
Next

Installation

Related Help Topics