payloadcms/payload
github.com/payloadcms/payload ↗ · 4000 files · 13.2 MB · scan capped
Explore the Docs · Community Help · Roadmap · View G2 Reviews [!IMPORTANT] Star this repo or keep an eye on it to follow along.
Overview
Payload is a configurable CMS and application backend for developers who want typed content models, an editor-facing React admin interface, and REST, GraphQL, and server-side APIs over the same data. Its configuration drives collections, globals, fields, authorization, hooks, and integrations; database and file-storage adapters separate application behavior from persistence. This brief examines commit e6cd442f40563b2dd95cebcc6a3ffaa2dbbc68f2, whose manifest identifies version 4.0.0-canary.37 and whose admin implementation includes shared framework boundaries beyond Next.js.
System map
The configuration and core Payload instance form the backend center of the system. Framework adapters expose that backend through HTTP handlers and server-rendered admin entrypoints, while shared UI code owns much of the admin implementation. Persistence is adapter-specific, with separate database, KV, email, and file-storage boundaries. The inspected workspace is a canary monorepo, so versioned source takes precedence over older architectural descriptions.
- The root is a private ESM monorepo at 4.0.0-canary.37; pnpm-workspace.yaml includes packages, tools, the test workspace, and four template workspaces, with pnpm 11.9.0 pinned.
- Generated Next.js app wiring delegates REST verbs to @payloadcms/next/routes, admin pages to RootPage, and server functions plus layout rendering to @payloadcms/next/layouts.
- The REST adapter calls handleEndpoints, whose Fetch Request/Response interface is documented for other backend frameworks; routing selects root, collection, or global endpoint tables.
- Shared admin renderRoot accepts injected context initialization, view adapters, redirect, and notFound functions; its route-key contract explicitly accommodates TanStack Start and Next.js remount differences.
- BasePayload initializes config.db and config.kv independently, then initializes a configured email adapter or falls back to consoleEmailAdapter.
- MongoDB creation uses Mongoose Model.create and session-aware transforms; postgresAdapter imports CRUD, version, transaction, and migration implementations from @payloadcms/drizzle.
- build:core excludes plugin and storage packages plus templates, build:all broadens package builds, and Turbo orders builds through dependency builds while caching dist output.
- Deployment documentation describes Next.js hosting with separately provisioned database, permanent file storage, email, and CDN requirements; the Astro example instead provides separate Payload and website development commands.
Feature catalog
The inspected features cover editor workflows, application APIs, authentication, uploads, localization, and background work. Configured schemas determine which entities and capabilities appear. CLI commands provide another operational surface, while optional packages add specialized product functionality. This catalog groups evidenced capabilities and does not claim exhaustive coverage of every package or screen.
- The default admin view registry includes dashboard, account, first-user creation, login, logout, inactivity logout, password recovery/reset, verification, unauthorized, and not-found screens.
- Collection REST endpoints provide count, create, bulk and single deletion, document access, list and single reads, duplicate, version listing/detail/restoration, and bulk or single PATCH updates.
- Payload exposes Local, REST, and GraphQL APIs; the Next GraphQL POST handler generates a schema from config, applies validation rules, and returns 404 when graphQL.disable is enabled.
- Local login supports configured email and/or username identities, account locking, optional verified-email enforcement, optional sessions, and opportunistic migration of stored password hashes.
- Creation supports drafts, autosave versions, localized publication status, and publishing accessible locales; scheduled publishing configuration adds a task during sanitization.
- Uploads support multipart files, staged upload instructions, URL inputs, and local writes; S3 options additionally expose direct client uploads and signed downloads.
- Built-in CLI commands cover document/global operations, schema and type/import-map generation, build, migration management, and job execution/scheduling; automatic job crons conditionally schedule and run queues.
- Documented optional features include Lexical rich text, iframe live preview using postMessage, and plugins for forms, MCP, tenancy, nested documents, redirects, search, Sentry, SEO, Stripe, import/export, and ecommerce.
Data flow
Configuration is transformed before runtime state is initialized. HTTP requests acquire authentication, query, locale, and translation context before endpoint handlers consume data. Collection operations own validation and lifecycle behavior, then delegate stored representations to adapters. Returned documents are transformed again for field visibility, population, localization, and hooks before crossing the response boundary.
- buildConfig sorts plugins by order, awaits each config transformation, invokes each storage adapter's init, and finally passes the resulting config to sanitizeConfig.
- createPayloadRequestFromWebRequest parses cookies, gets a cached Payload instance with crons enabled, parses query strings with depth 10 and arrayLimit 1000, and normalizes configured locales.
- createPayloadRequest attaches Payload, context, i18n, user, and a request dataloader; the web wrapper then executes auth strategies and attaches the resulting user and response headers.
- Internal POST/PATCH endpoint wrappers parse data/files and body locales before calling the original handler; JSON becomes req.data, while multipart _payload supplies data and file parts populate req.files/req.file.
- The client Form reduces fields to values, runs optional beforeSubmit and form validation, builds FormData, then either sends an HTTP request with Accept-Language or calls a function action.
- createLocal resolves a collection, defaults overrideAccess to false, constructs request context, and resolves req.file from an explicit file or filePath before entering the shared create path.
- The MongoDB adapter transforms application data for writing, assigns database identity, obtains the request session, calls Model.create, and converts/transforms the stored result back for reading unless returning is false.
- After persistence, createOperation sanitizes internal fields, optionally saves a version and sends verification email, runs field/collection afterRead and afterChange hooks, then cleans temporary files and commits its transaction.
Behavior traces
Three concrete paths were followed through implementation: instance startup, REST document creation through MongoDB persistence, and REST login through cookie issuance. Startup shares concurrent initialization work and conditionally activates development and cron behavior. Creation branches for auth collections, uploads, drafts, and versions before shaping the response. Login authenticates before starting its remaining transaction and includes explicit session cleanup on failure.
- Startup begins getPayload → cache lookup by key/default → shared initialization promise → new BasePayload().init; initialization failures clear the promise and mark the error as payloadInitError.
- BasePayload.init awaits config → initializes logger → requires secret → builds the active/previous-secret keyring → registers collections/blocks → initializes DB and KV → optionally connects DB → initializes email.
- Startup then collects custom and API-key auth strategies, appends local JWT when enabled, runs options/config onInit unless disabled, and invokes _initializeCrons only when requested.
- REST creation runs exported POST → Next handlerBuilder → handleEndpoints → createPayloadRequestFromWebRequest → endpoint matching and routeParams injection → wrapped body parsing → createHandler → createOperation.
- createOperation starts a transaction, strips submitted upload identity for non-overridden upload requests, runs beforeOperation, enforces create access unless overridden, generates file data, then runs field/collection validation and change hooks.
- Creation writes local files unless disabled, calls registerLocalStrategy for local-auth collections or payload.db.create otherwise, optionally saves versions, shapes results through hooks, and commits; errors clean temporary files and kill the transaction.
- REST login runs loginHandler → loginWithCookie → loginOperation → normalized identity query excluding trashed users → db.findOne → checkLoginPermission → authenticateLocalStrategy; failed passwords increment attempts when configured, and unverified users are rejected when verification is enabled.
- Successful login starts a transaction → rechecks lock state → adds a session → optionally rehashes the password → resets attempts → runs beforeLogin → signs JWT → applies user read access and afterOperation → commits; loginWithCookie generates the cookie before optional token removal, and the handler returns Set-Cookie.
Testing signals
Tests and CI were inspected, not executed; no passing result is asserted. Vitest separates unit, browser-component, RSC, integration, and evaluation projects, while Playwright covers browser workflows and visual comparisons. Read assertions demonstrate intended coverage of request construction, authentication, authorization, password migration, and selected accessibility behavior. The inventory and inspection are bounded, and neither test existence nor CI configuration establishes exhaustive coverage or runtime correctness.
- Vitest selects package/tool/unit specs for the Node unit project, TSX specs for Chromium component tests, and Next RSC specs under react-server resolution conditions.
- The integration project selects test/**/*int.spec.ts, disables file parallelism, uses 90-second hook/test timeouts, and loads test/vitest.setup.ts; CI configures two Vitest retries.
- Shared integration fixtures initialize/destroy Payload once per file, ordinarily reset and seed before each payload-backed test, and provide REST/SDK clients; the inspected auth suite explicitly disables between-test resets.
- Read auth assertions cover successful REST login, removal of restricted user fields from login responses, owned preference updates, first-user registration rejection, and legacy password rehashing.
- createPayloadRequest unit tests use mock Payload objects to check supplied URL precedence, configured serverURL fallback, and localhost fallback; these assertions do not exercise a real database or HTTP server.
- The inspected WCAG Playwright suite checks the login logo's accessible name and lack of tab stop, plus column-editor headings and checkbox labels; browser configuration defines only a Chromium project.
- Main CI configures unit/component/type checks and sharded integration tests; integration runs can exclude Canary-named tests when the upstream Next canary package probe reports an incomplete publish.
- Production E2E CI excludes @visual tests, which run in a separate path-gated visual job using pinned Playwright Docker tooling; the scripts and workflow were inspected, not executed, so their current outcomes and uninspected flows remain unverified.
Risk map
These are source observations and explicitly marked hypotheses, not confirmed vulnerabilities. Important review boundaries include privileged API options, development autologin, secret rotation, request rewriting, configuration caches, and filesystem side effects. The inspected code contains protections as well as intentional trusted bypasses. Runtime exploitability, production configuration, and whole-repository test gaps were not established.
- createOperation skips collection create access when overrideAccess is truthy; createLocal defaults it to false. The documented low-level payload.db.batchProcessing method does not run Local API access, hooks, field validation, or upload handling, and leaves transaction lifecycle to its caller.
- JWTAuthentication can return a configured autologin user when no token is present and DisableAutologin is not true; that lookup uses overrideAccess: true and requires an object autologin configuration without prefillOnly.
- Initialization accepts active and previous secrets into a keyring; JWT verification tries every key, then checks authVersion, typed identity references, an auth-enabled local collection, and configured session membership.
- External URL resolution enforces upload policy, HTTP(S), and an allow-list by default, suppresses forwarded headers by default, and checks downloaded size; trusted callers may opt out of requiring an allow-list.
- Hypothesis: file or email side effects may need compensation after later create failures because local uploads and verification email precede commit, while the shown catch path removes temporary files and rolls back the database transaction. (inferred)
- The JSON POST-to-GET override branch appends fallbackLocale using data.depth rather than data.fallbackLocale, and uses '&' even when no locale query was added; this is a source-level discrepancy requiring reproduction, not a confirmed security issue.
- getPayload caches by supplied key or 'default', rather than comparing configuration identity; getGraphql uses one global schema cache outside development. Multiple-config integrations must account for these cache boundaries.
- The root development Next config sets ignoreBuildErrors: true; development Payload initialization can spawn generate:types through a Node child process, and production test-preparation scripts delete/recreate working directories.
Extension points
Configuration transformation is the primary extension mechanism. Runtime factories bind database, storage, authentication, and email implementations to a Payload instance. Endpoint tables and CLI command definitions expose additional behavior without replacing the core operation pipeline. Admin components, lifecycle hooks, jobs, and rich-text features provide more targeted customization surfaces.
- Plugins are ordered config-to-config transformations: buildConfig sorts by plugin.order with zero as the default and awaits each result before sanitization.
- Storage adapters belong in config.storage and must expose init; s3Storage returns a named adapter with collection membership and an init function that binds cloud-storage behavior.
- createDatabaseAdapter supplies default batching, copy, migration, and null transaction implementations that adapter arguments can override; postgresAdapter also accepts schema lifecycle hooks and query operator handlers.
- Root, collection, and global endpoint arrays are dispatched by method plus path-to-regexp matching; route parameters receive the resolved collection/global slug, and endpoints:false disables that endpoint surface.
- Custom auth strategies are collected from auth-enabled collections before API-key/local JWT behavior; executeAuthStrategies invokes them in order, merges response headers, logs thrown errors, and returns on the first user.
- config.cli.commands overrides built-ins and accepts disabled entries or dynamically imported command definitions; loading resolves paths relative to configDir and validates name/alias conflicts.
- Admin customization types expose providers, navigation, sidebar tabs, user-menu settings, named/custom views, dashboard widgets, dependencies, and import-map generators.
- Collection hooks can transform create data before validation/change and results after read/change; jobs tasks/workflows enable internal queue collections, while Lexical exposes replaceable feature composition.
Contributor handoff
Read the relevant configuration, operation, adapter, and feature fixture before editing across boundaries. Tests and CI were inspected, not executed; the suggested commands are future verification choices, not results from this investigation. The inventory is bounded, and environment files were intentionally excluded under the read-only authority. Preserve small changes and distinguish runtime behavior from stale prose, configured bypasses, and generated wiring.
- Use the current manifest and source for version-sensitive decisions: package.json says 4.0.0-canary.37, while AGENTS.md architecture notes still describe Payload 3.x and incorrectly generalize database adapters as Drizzle-based relative to MongoDB implementation.
- Before changing startup or config features, read buildConfig, sanitizeConfig, and BasePayload.init: sanitization injects internal collections and jobs, and initialization binds the actual runtime adapters.
- For HTTP mutations, inspect handleEndpoints, wrapInternalEndpoints, and the shared collection operation; body parsing and slug injection occur before operation-level authorization and persistence.
- Follow repository conventions for object arguments, types, separate import type statements, translated config labels, stable hook arguments, and logger objects using msg/err.
- Server components must reference client exports through the prescribed client bundle, and explicit named exports are required for new bundling work; the shared root renderer demonstrates the client-boundary import.
- Payload-backed integration tests should use the shared test.suite wrapper and fixture arguments; fixtures own initialization/reset/destruction, while files and other non-database side effects require test cleanup.
- Future verification can start with focused unit or integration scripts, then adapter-specific integration or production E2E checks as needed; tests and CI were inspected, not executed, and production preparation contains destructive directory-reset steps that are outside this read-only task.
- For UI changes, apply the repository accessibility requirements and token/CSS conventions; generate visual baselines only in the pinned Playwright Docker environment, and do not infer correctness from Next builds that ignore type errors.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 7362 | 95% |
| JSON | 471 | docs/config |
| CSS | 457 | docs/config |
| Markdown | 326 | docs/config |
| JavaScript | 200 | 3% |
| Sass | 136 | 2% |
| YAML | 66 | docs/config |
| Shell | 17 | 0% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (928 files) app/ (12 files)
Source layout — app/
| Path | Files |
|---|---|
app/(app)/ | 2 |
app/(payload)/ | 8 |
app/my-route/ | 1 |
app/global-error.tsx | 1 |
Repository structure
| Top-level path | Files |
|---|---|
packages/ | 928 |
test/ | 927 |
templates/ | 927 |
examples/ | 774 |
docs/ | 174 |
.github/ | 108 |
tools/ | 62 |
scripts/ | 13 |
Docs found: AGENTS.mdCONTRIBUTING.mdLICENSE.mdREADME.md
Package
package.json — payload-monorepo v4.0.0-canary.37, 74 declared dependencies.
@ai-sdk/anthropic@ai-sdk/openai@axe-core/playwright@clack/prompts@guidepup/guidepup@guidepup/playwright@libsql/client@next/bundle-analyzer@payloadcms/db-postgres@payloadcms/eslint-config@payloadcms/eslint-plugin@payloadcms/live-preview-react
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.env.example— Required env vars.github/workflows/activity-notifications.yml— GitHub Actions workflow.github/workflows/ai-reviewer.yml— GitHub Actions workflow.github/workflows/audit-dependencies.yml— GitHub Actions workflow.github/workflows/dispatch-event.yml— GitHub Actions workflow.github/workflows/label-on-change.yml— GitHub Actions workflow.github/workflows/lock-issues.yml— GitHub Actions workflow.github/workflows/main.yml— GitHub Actions workflow
Structural health signals
Average score 6.3/10 across 96 analyzed source files; 54 hotspots surfaced.
test/access-control/getConfig.ts— 1513 lines, score 5 (Large file, Deep nesting)test/evals/components/EvalDashboard/CompareTable.tsx— 1481 lines, score 5 (Large file, Deep nesting)test/database/getConfig.ts— 1266 lines, score 5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
e6cd442f40562026-10-02 — feat!: add database copy method (#18453)401d1d87ede92026-10-02 — feat: add database batch processing foundation (#18455)cfad46020ff82026-10-02 — feat: export batchProcessing utility (#18454)b753f9ef11762026-10-02 — test: fail fast on e2e server crash, fix throttle leak, drop 1s fixture delays (#18444)d5ba54edeadc2026-10-02 — fix: memory leak on version and draft operations with mongodb (#18445)