0
# Payload CMS
1

2
Payload is a headless content management system and application framework that provides a complete backend solution for web applications. It combines a powerful admin interface built with React, flexible content modeling capabilities, and comprehensive APIs (REST, GraphQL, and Local Node APIs) to enable developers to build scalable web applications and websites.
3

4
## Package Information
5

6
- **Package Name**: payload
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install payload`
10

11
## Core Imports
12

13
```typescript
14
import payload from "payload";
15
import { Payload } from "payload";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const payload = require("payload");
22
const { Payload } = require("payload");
23
```
24

25
## Basic Usage
26

27
```typescript
28
import payload from "payload";
29

30
// Initialize Payload
31
await payload.initAsync({
32
  secret: process.env.PAYLOAD_SECRET,
33
  mongoURL: process.env.DATABASE_URI,
34
  express: app, // Your Express app
35
});
36

37
// Create a document
38
const newPost = await payload.create({
39
  collection: "posts",
40
  data: {
41
    title: "My First Post",
42
    content: "Hello, world!",
43
    status: "published",
44
  },
45
});
46

47
// Find documents
48
const posts = await payload.find({
49
  collection: "posts",
50
  where: {
51
    status: {
52
      equals: "published",
53
    },
54
  },
55
});
56

57
// Update a document
58
const updatedPost = await payload.update({
59
  collection: "posts",
60
  id: postId,
61
  data: {
62
    title: "Updated Title",
63
  },
64
});
65
```
66

67
## Architecture
68

69
Payload is built around several key components:
70

71
- **Payload Class**: Main CMS instance providing configuration, database connections, and operation methods
72
- **Collections**: Define content types with fields, hooks, access control, and admin configuration
73
- **Globals**: Singleton documents for site-wide content like settings and navigation
74
- **Fields**: Rich set of field types for modeling data (text, rich text, relationships, uploads, etc.)
75
- **Authentication**: Built-in user management with configurable auth strategies
76
- **Access Control**: Field-level and document-level permissions system
77
- **Admin Panel**: Auto-generated React admin interface with customizable components
78
- **APIs**: REST, GraphQL, and Local Node.js APIs generated from your configuration
79

80
## Capabilities
81

82
### Core Operations
83

84
Primary CRUD operations for interacting with collections and managing content. Essential for all content management workflows.
85

86
```typescript { .api }
87
// Create operations
88
function create<T>(options: CreateOptions<T>): Promise<T>;
89

90
// Read operations  
91
function find<T>(options: FindOptions): Promise<PaginatedDocs<T>>;
92
function findByID<T>(options: FindByIDOptions): Promise<T>;
93

94
// Update operations
95
function update<T>(options: UpdateOptions<T>): Promise<T>;
96

97
// Delete operations
98
function delete<T>(options: DeleteOptions): Promise<T>;
99

100
interface CreateOptions<T> {
101
  collection: string;
102
  data: Partial<T>;
103
  depth?: number;
104
  locale?: string;
105
  fallbackLocale?: string;
106
  user?: User;
107
  overrideAccess?: boolean;
108
  showHiddenFields?: boolean;
109
}
110

111
interface FindOptions {
112
  collection: string;
113
  where?: Where;
114
  sort?: string;
115
  limit?: number;
116
  page?: number;
117
  depth?: number;
118
  locale?: string;
119
  fallbackLocale?: string;
120
  user?: User;
121
  overrideAccess?: boolean;
122
  showHiddenFields?: boolean;
123
}
124
```
125

126
[Core Operations](./core-operations.md)
127

128
### Global Operations
129

130
Operations for managing global documents (singleton content like site settings, navigation, etc.).
131

132
```typescript { .api }
133
function findGlobal<T>(options: FindGlobalOptions): Promise<T>;
134
function updateGlobal<T>(options: UpdateGlobalOptions): Promise<T>;
135

136
interface FindGlobalOptions {
137
  slug: string;
138
  depth?: number;
139
  locale?: string;
140
  fallbackLocale?: string;
141
  user?: User;
142
  overrideAccess?: boolean;
143
  showHiddenFields?: boolean;
144
}
145

146
interface UpdateGlobalOptions {
147
  slug: string;
148
  data: any;
149
  depth?: number;
150
  locale?: string;
151
  fallbackLocale?: string;
152
  user?: User;
153
  overrideAccess?: boolean;
154
  showHiddenFields?: boolean;
155
}
156
```
157

158
[Global Operations](./global-operations.md)
159

160
### Authentication System
161

162
Complete user authentication and management system with login, password reset, email verification, and account locking.
163

164
```typescript { .api }
165
function login<T>(options: LoginOptions): Promise<LoginResult & { user: T }>;
166
function forgotPassword(options: ForgotPasswordOptions): Promise<ForgotPasswordResult>;
167
function resetPassword(options: ResetPasswordOptions): Promise<ResetPasswordResult>;
168
function unlock(options: UnlockOptions): Promise<boolean>;
169
function verifyEmail(options: VerifyEmailOptions): Promise<boolean>;
170

171
interface LoginResult {
172
  token?: string;
173
  user: User;
174
  exp?: number;
175
}
176

177
interface LoginOptions {
178
  collection: string;
179
  data: {
180
    email: string;
181
    password: string;
182
  };
183
  req?: PayloadRequest;
184
  res?: Response;
185
  depth?: number;
186
  locale?: string;
187
  fallbackLocale?: string;
188
  overrideAccess?: boolean;
189
  showHiddenFields?: boolean;
190
}
191
```
192

193
[Authentication System](./authentication.md)
194

195
### Version Control
196

197
Document versioning system for tracking changes and restoring previous versions of content.
198

199
```typescript { .api }
200
function findVersions<T>(options: FindVersionsOptions): Promise<PaginatedDocs<T>>;
201
function findVersionByID<T>(options: FindVersionByIDOptions): Promise<T>;  
202
function restoreVersion<T>(options: RestoreVersionOptions): Promise<T>;
203
function findGlobalVersions<T>(options: FindGlobalVersionsOptions): Promise<PaginatedDocs<T>>;
204
function findGlobalVersionByID<T>(options: FindGlobalVersionByIDOptions): Promise<T>;
205
function restoreGlobalVersion<T>(options: RestoreGlobalVersionOptions): Promise<T>;
206
```
207

208
[Version Control](./version-control.md)
209

210
### Configuration System
211

212
Comprehensive configuration system for defining collections, globals, fields, authentication, and admin settings.
213

214
```typescript { .api }
215
interface Config {
216
  serverURL?: string;
217
  collections?: CollectionConfig[];
218
  globals?: GlobalConfig[];
219
  admin?: AdminConfig;
220
  auth?: AuthConfig;
221
  email?: EmailConfig;
222
  upload?: UploadConfig;
223
  localization?: LocalizationConfig;
224
  typescript?: TypeScriptConfig;
225
  graphQL?: GraphQLConfig;
226
  cors?: CORSConfig;
227
  csrf?: CSRFConfig;
228
  express?: ExpressConfig;
229
  routes?: {
230
    admin?: string;
231
    api?: string;
232
    graphQL?: string;
233
    graphQLPlayground?: string;
234
  };
235
  rateLimit?: RateLimitConfig;
236
  hooks?: {
237
    afterError?: AfterErrorHook;
238
  };
239
  telemetry?: boolean;
240
  debug?: boolean;
241
  loggerOptions?: LoggerOptions;
242
}
243
```
244

245
[Configuration System](./configuration.md)
246

247
### Field Types
248

249
Rich set of field types for modeling content including text fields, relationships, file uploads, rich text editing, and complex nested structures.
250

251
```typescript { .api }
252
// Core field types
253
interface TextField extends BaseField {
254
  type: 'text';
255
  maxLength?: number;
256
  minLength?: number;
257
  hasMany?: boolean;
258
}
259

260
interface RichTextField extends BaseField {
261
  type: 'richText';
262
  editor?: RichTextEditorConfig;
263
}
264

265
interface RelationshipField extends BaseField {
266
  type: 'relationship';
267
  relationTo: string | string[];
268
  hasMany?: boolean;
269
  maxDepth?: number;
270
}
271

272
interface UploadField extends BaseField {
273
  type: 'upload';
274
  relationTo: string;
275
}
276

277
interface ArrayField extends BaseField {
278
  type: 'array';
279
  fields: Field[];
280
  minRows?: number;
281
  maxRows?: number;
282
}
283
```
284

285
[Field Types](./field-types.md)
286

287
### User Preferences
288

289
System for storing and managing user-specific settings, UI state, and document preferences.
290

291
```typescript { .api }
292
function findPreference<T>(options: PreferenceRequest): Promise<T | null>;
293
function updatePreference<T>(options: PreferenceUpdateRequest): Promise<Preference>;
294
function deletePreference(options: PreferenceRequest): Promise<Preference | null>;
295

296
interface PreferenceRequest {
297
  key: string;
298
  user: User;
299
  req: PayloadRequest;
300
  overrideAccess?: boolean;
301
}
302

303
interface PreferenceUpdateRequest extends PreferenceRequest {
304
  value: T;
305
}
306
```
307

308
[User Preferences](./preferences.md)
309

310
## Core Types
311

312
```typescript { .api }
313
// Main Payload class
314
class Payload {
315
  config: SanitizedConfig;
316
  collections: { [slug: string]: Collection };
317
  globals: Globals;
318
  logger: pino.Logger;
319
  express: Express;
320
  router: Router;
321
  
322
  // Initialization
323
  init(options: InitOptions): void;
324
  initAsync(options: InitOptions): Promise<void>;
325
  
326
  // Utility methods
327
  getAdminURL(): string;
328
  getAPIURL(): string;
329
  
330
  // Crypto utilities
331
  encrypt: (text: string) => string;
332
  decrypt: (encryptedText: string) => string;
333
}
334

335
// Initialization options
336
interface InitOptions {
337
  secret: string;
338
  mongoURL?: string | false;
339
  express?: Express;
340
  email?: EmailOptions;
341
  local?: boolean;
342
  onInit?: () => void | Promise<void>;
343
}
344

345
// Result types
346
interface PaginatedDocs<T> {
347
  docs: T[];
348
  totalDocs: number;
349
  limit: number;
350
  totalPages: number;
351
  page: number;
352
  pagingCounter: number;
353
  hasPrevPage: boolean;
354
  hasNextPage: boolean;
355
  prevPage?: number;
356
  nextPage?: number;
357
}
358

359
// Base document types
360
interface TypeWithID {
361
  id: string | number;
362
  createdAt?: string;
363
  updatedAt?: string;
364
}
365

366
interface TypeWithVersion<T> extends TypeWithID {
367
  version: T;
368
  createdAt: string;
369
  updatedAt: string;
370
}
371

372
// Query types
373
interface Where {
374
  [key: string]: any;
375
  and?: Where[];
376
  or?: Where[];
377
}
378

379
// User and auth types
380
interface User extends TypeWithID {
381
  email?: string;
382
  resetPasswordToken?: string;
383
  resetPasswordExpiration?: string;
384
  salt?: string;
385
  hash?: string;
386
  loginAttempts?: number;
387
  lockUntil?: number;
388
}
389

390
// Base error types
391
class APIError extends Error {
392
  status: number;
393
  data?: any;
394
  constructor(message?: string, status?: number, data?: any);
395
}
396

397
class ValidationError extends APIError {
398
  constructor(message?: string, data?: any);
399
}
400

401
class Forbidden extends APIError {
402
  constructor(message?: string);
403
}
404

405
class NotFound extends APIError {
406
  constructor(message?: string);
407
}
408

409
// Authentication errors
410
class AuthenticationError extends APIError {
411
  constructor(message?: string);
412
}
413

414
class LockedAuth extends APIError {
415
  constructor(message?: string);
416
}
417

418
// Configuration errors
419
class InvalidConfiguration extends APIError {
420
  constructor(message?: string);
421
}
422

423
class DuplicateCollection extends APIError {
424
  constructor(message?: string, slug?: string);
425
}
426

427
class DuplicateGlobal extends APIError {
428
  constructor(message?: string, slug?: string);
429
}
430

431
// Field errors
432
class InvalidFieldName extends APIError {
433
  constructor(message?: string, fieldName?: string);
434
}
435

436
class InvalidFieldRelationship extends APIError {
437
  constructor(message?: string);
438
}
439

440
class MissingFieldType extends APIError {
441
  constructor(message?: string);
442
}
443

444
class MissingFieldInputOptions extends APIError {
445
  constructor(message?: string);
446
}
447

448
// Collection errors
449
class MissingCollectionLabel extends APIError {
450
  constructor(message?: string, slug?: string);
451
}
452

453
class TimestampsRequired extends APIError {
454
  constructor(message?: string);
455
}
456

457
// File upload errors
458
class FileUploadError extends APIError {
459
  constructor(message?: string);
460
}
461

462
class ErrorDeletingFile extends APIError {
463
  constructor(message?: string);
464
}
465

466
class MissingFile extends APIError {
467
  constructor(message?: string);
468
}
469
```