Registry / web-framework / payload

payload

JSON →
library3.83.0jsnpmunverified

Payload is an open-source, TypeScript-first headless CMS and application framework built on Node.js and React, frequently integrated with Next.js for full-stack applications. It is currently at version 3.83.0 and maintains an active release cadence, with multiple minor versions and bug fixes published monthly, indicating continuous and rapid development. A key differentiator is its code-first configuration approach, allowing developers to define collections, globals, and other configurations programmatically using TypeScript. This facilitates strong version control, type safety, and a developer-centric workflow, distinguishing it from CMS platforms that primarily rely on UI-driven configuration. Payload also provides a robust GraphQL API out-of-the-box, flexible authentication mechanisms, and a customizable, self-hosted admin panel, making it suitable for both content management and complex application backends.

web-frameworkawsgcpazurehttp-networking
npm install payload
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · PAYLOAD
P
payload
web-frameworkjavascriptv3.83.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

payload
✓ import payload from 'payload';
✗ const payload = require('payload');
Payload is primarily designed for ESM environments, especially with Next.js App Router in v3. While CommonJS might work in some server-side contexts, ESM is the idiomatic and recommended approach. The default export is the Payload instance.
buildConfig
✓ import { buildConfig } from 'payload/config';
✗ import buildConfig from 'payload/config'; import { buildConfig } from 'payload';
Configuration utilities like `buildConfig` are named exports from the `payload/config` module, not the main 'payload' entry point. Ensure correct path for schema definition.
CollectionConfig
✓ import { CollectionConfig } from 'payload/types';
✗ import { CollectionConfig } from 'payload/config';
Type definitions for Payload schemas (e.g., `CollectionConfig`, `GlobalConfig`, `Field`) are available from the `payload/types` module for TypeScript users.
User
✓ import type { User } from 'payload/generated-types';
✗ import { User } from 'payload/dist/collections/Users/types'; // (example) import { User } from 'payload/types';
For dynamically generated types based on your specific Payload configuration (like `User`, `Post`, etc.), import them from `payload/generated-types`. This file is generated by Payload during development.

This quickstart demonstrates a minimal Payload configuration with two collections (Users and Posts), including authentication, basic fields, and relationship fields. It shows the `buildConfig` utility and how to define schemas. It also outlines the typical server initialization process.

import { buildConfig } from 'payload/config'; import path from 'path'; const Users = { slug: 'users', auth: true, admin: { use=>: 'Email', }, fields: [ { name: 'name', type: 'text', }, ], }; export default buildConfig({ serverURL: process.env.PAYLOAD_PUBLIC_SERVER_URL ?? 'http://localhost:3000', admin: { user: 'users', }, collections: [ Users, { slug: 'posts', fields: [ { name: 'title', type: 'text', required: true, }, { name: 'content', type: 'richText', }, { name: 'author', type: 'relationship', relationTo: 'users', }, ], }, ], typescript: { outputFile: path.resolve(__dirname, 'payload-types.ts'), }, graphQL: { schemaOutputFile: path.resolve(__dirname, 'generated-schema.graphql'), }, }); // To run this, you would typically have a server entry point like: // import payload from 'payload'; // import express from 'express'; // import { connect } from 'mongoose'; // or '@payloadcms/db-postgres' // const app = express(); // async function start() { // await connect(process.env.MONGODB_URI ?? 'mongodb://localhost/payload'); // await payload.init({ // secret: process.env.PAYLOAD_SECRET ?? 'super-secret-default-key', // express: app, // onInit: () => { // payload.logger.info(`Payload Admin URL: ${payload.getAdminURL()}`); // }, // }); // app.listen(3000, async () => { // payload.logger.info('Express is listening on port 3000'); // }); // } // start();
payload --version
Debug
Known issues
breakingMigrating from Payload v2 to v3 involves significant architectural changes. The Admin Panel was replatformed from a React Router SPA to the Next.js App Router, deprecating `admin.bundler` property and bundler packages like `@payloadcms/bundler-webpack` and `@payloadcms/bundler-vite`. Custom components and views require updating import paths and interfaces.
fix
Refer to the official Payload v2 to v3 migration guide on the Payload CMS website. This will involve deleting `admin.bundler` from your config, uninstalling old bundler packages, and updating custom UI components. Data migration scripts may also need careful review and adjustment.
affects: >=3.0.0
breakingEnvironment variables prefixed with `PAYLOAD_PUBLIC` are no longer available on the client-side in v3. This change aligns with Next.js's server-side rendering capabilities and impacts how client-side code accesses public environment variables.
fix
Adjust your application logic to ensure client-side code does not directly rely on `PAYLOAD_PUBLIC_` prefixed variables. Pass necessary public configuration through props to client components or utilize server components where appropriate.
affects: >=3.0.0
gotchaDependency mismatches are a common source of cryptic runtime errors (e.g., 'Cannot destructure property 'config' of undefined') in Payload v3. All `payload`, `@payloadcms/*`, `react`, `react-dom`, and `next` packages must be installed at *exactly* the same version. Using caret (`^`) ranges can lead to inconsistencies.
fix
Always pin exact versions for all Payload-related packages in your `package.json` (e.g., `"payload": "3.83.0"` instead of `"^3.83.0"`). Delete `node_modules`, `package-lock.json` (or equivalent lock file), `.payload/`, and `.next/` directories, then run `npm install` (or `pnpm install`) to force a clean, consistent dependency resolution and rebuild.
affects: >=3.0.0
gotchaPayload builds (e.g., `npm run build`) can sometimes fail if an active database connection is not available at build time. This contradicts documentation and can be problematic in CI/CD environments where database access might be restricted during the build stage.
fix
Ensure your build environment has access to a database connection, or configure your Payload application to defer database connection until runtime, if possible. Monitor GitHub issues related to 'Build Fails Due to Missing Database Connection' for official fixes or workarounds.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: Cannot destructure property 'config' of 'ue(...)' as it is undefined.
This typically indicates a React context provider issue, often caused by inconsistent versions of `payload` or `@payloadcms/*` packages, or `react`/`react-dom` in your dependency tree, especially in monorepos.
fix
Ensure all `payload` and `@payloadcms/*` packages, along with `react`, `react-dom`, and `next`, are pinned to identical versions in your `package.json`. Remove `node_modules`, `package-lock.json`, `.payload`, and `.next` directories, then reinstall dependencies.
ERROR (payload): Error: cannot connect to MongoDB. Details: URI does not have hostname, domain name and tld
Payload failed to establish a connection with the database. This can be due to an incorrect `MONGODB_URI` environment variable, network issues (firewall, IP whitelisting), incorrect credentials (e.g., special characters in passwords needing URI encoding), or the database server not running.
fix
Verify your `MONGODB_URI` in `.env` is correct and properly formatted. Ensure special characters in passwords are URI-encoded. Check network access, firewall rules, and if your database server is active and accessible. Consider using a tool like MongoDB Compass to test the connection independently.
Unauthorized, you must be logged in to make this request
This error occurs when an authentication cookie is not being set or accepted correctly, or when access control functions deny the request.
fix
Review your Payload configuration for `CORS`, `CSRF`, and `cookie` settings. Explicitly whitelist your frontend domain in `CORS` rather than using `*`. Check browser developer tools for cookie rejection warnings to diagnose misconfigured cookie domain or security flags. Verify your access control functions are correctly implemented.
CORS error when accessing with other ports, even with cors: '*'
Despite setting `cors: '*'` in `payload.config.ts`, browsers may still block requests due to preflight checks or specific browser security policies. This is often an issue when the serverURL is not correctly configured for the API.
fix
Explicitly list allowed origins in your `cors` array (e.g., `cors: ['http://localhost:3000', 'http://localhost:8080']`). Ensure your `serverURL` in `payload.config.ts` accurately reflects the URL where your Payload API is accessible. For specific HTTP methods, ensure they are correctly cased (e.g., 'PATCH' not 'patch').
Upgrade
Version history
3.83.0latest on npm
Audit
Dependencies
graphqlrequiredRequired for GraphQL API functionality, often needed by consumer applications interacting with Payload's GraphQL endpoint.
Agent activity
53 hits · last 30 days
node
46
OpenAI (training)
1
Resources
githubhttps://github.com/payloadcms/payload ↗
packagehttps://www.npmjs.com/package/payload ↗
homepagehttps://payloadcms.com ↗