Payload CMS 4.0 Is Coming And It Is a Major Leap Forward
Payload CMS 4.0 is no longer just a roadmap item. With active canary releases now at v4.0.0-canary.37 and an official migration guide merged into the main branch on GitHub, the shape of Payload 4 is concrete and production teams need to start preparing now.
The latest stable 3.x release remains Payload v3.90.2, but the v4 canary ecosystem is publishing across all packages including the new @payloadcms/tanstack-start adapter.
What Is New in Payload CMS 4.0
1. Redesigned Admin UI with Semantic CSS Tokens
The admin panel receives its most substantial design refresh since the 3.0 launch. Payload 4 eliminates the legacy Sass build pipeline entirely, replacing it with pure CSS and semantic design tokens. This means effortless admin theming via CSS variable overrides with no more compiling Sass assets. Tailwind CSS and component libraries like shadcn/ui can now be used inside custom admin views without style conflicts, thanks to isolated CSS reset strategies.
New organizational features include native folders, tags, and expandable sidebar tabs, reducing the need for community plugins like nested-docs.
2. TanStack Start Support (Experimental)
Payload 4 introduces the @payloadcms/tanstack-start canary adapter, decoupling Payload from its tight Next.js dependency. Teams seeking ultra-fast Vite HMR, alternative server runtimes, or strict decoupling from Vercel can now evaluate Payload with TanStack Start and TanStack Router. Next.js remains the primary tier-one platform, but the framework-adapter pattern opens the door to a broader ecosystem.
3. MCP (Model Context Protocol) and AI Agent Workflows
AI-assisted engineering is a primary focal point of Payload 4. The @payloadcms/plugin-mcp package is published as a first-class v4 canary. Key advancements include:
- Opt-out tools by default: built-in collection and global tools are exposed automatically unless disabled
- Runtime JSON Schema ingestion: fields expose standard JSON Schemas at runtime, dramatically reducing AI hallucination in LLM tool-calling contexts
- Payload Skills: standardized agent skill definitions and evaluation suites for idiomatic Payload 4 patterns
4. Critical Breaking Changes You Must Know
Payload 4 introduces several security-hardening defaults that will break existing codebases if not addressed:
- overrideAccess defaults to false: Local API calls no longer bypass access control automatically. Any internal cron jobs, migrations, or seed scripts that omit overrideAccess: true will fail or return empty datasets.
- Default relationship depth drops from 2 to 1: Prevents catastrophic query cascades on nested schemas. Restore with depth: 2 on specific queries or set defaultDepth: 2 globally.
- Versioning enabled by default: All collections and globals will have versioning turned on unless explicitly set to versions: false. This will generate new _versions database tables on upgrade.
- Slate rich-text adapter removed: @payloadcms/richtext-slate is completely deleted. Lexical is now the sole official rich-text engine.
5. Lexical 0.50 Upgrade
Payload 4 upgrades the underlying Lexical framework from 0.41 to Lexical 0.50. The experimental EXPERIMENTAL_TableFeature is now stabilized and renamed to TableFeature. Link node structures are validated against stricter schemas.
6. New Minimum Runtime Requirements
Payload 4 requires modern infrastructure:
- Node.js 24.15.0 or higher
- Next.js 16.2.6 or higher (if using the Next adapter)
- TypeScript 6.0.3 or higher
How to Prepare for the Upgrade
The Payload team provides an official automated codemod to handle mechanical transformations. Run: npx @payloadcms/codemod@latest
The codemod will inject versions: false into unversioned collections, replace deprecated request utilities, update global component structures, and migrate database adapter imports.
Key Takeaway: Payload 4.0 is a significant architectural leap, not just a version bump. The security hardening defaults will require active code review before upgrading. Start auditing your Local API calls and collection configurations now.
Hashtags: #PayloadCMS #NextJS #WebDevelopment #HeadlessCMS #ReactJS #TypeScript #AIIntegration #MCP
Resources: