Payload 4
Run payload-better-auth on the Payload 4 beta from the next release line, what is already handled, and the known gap.
Payload 4 is in beta and supported early. The plugin talks to Payload only through its public Local API and admin UI exports, so a new Payload major is a small set of mechanical changes. The Payload 4 line follows Payload's canary releases, with the aim of a stable release when Payload 4.0 ships.
| You run | Install | npm tag |
|---|---|---|
Payload 3 (>=3.90 <4) | @delmaredigital/payload-better-auth | latest (0.14.x) |
Payload 4 beta (>=4.0.0-beta.0 <4.0.0-canary.0 or >=4.0.0-canary.37 <5) | @delmaredigital/payload-better-auth@next | next (0.40.0-next.x) |
npm i @delmaredigital/payload-better-auth@0.40.0-next.2Requirements
payload/@payloadcms/ui>=4.0.0-beta.0 <4.0.0-canary.0 || >=4.0.0-canary.37 <5,next>=16.4.1 <17, Node>=24.22.1, plus the rest of Payload's v4 migration guide.- Better Auth requirements are unchanged.
- Pin an exact version. Prereleases follow Payload's canaries and can change from one build to the next.
Already handled on both majors
- The plugin's Local API lookups pass
overrideAccess: trueexplicitly. Payload 4 flips the default tofalse. - Generated auth collections opt out of Payload 4's default versioning, so there are no
_versionstables holding old sessions, tokens or password hashes.
Authorship and atomic writes
From 0.40.0-next.2, the Payload 4 line includes 0.14.2's atomic Postgres writes, and generated Better Auth collections set authorship: false. Payload 4 defaults authorship on, and the hooks on its injected createdBy/updatedBy fields would make the default 'auto' policy refuse every collection and fall back to the non-atomic Local API path. Better Auth writes without a request user, so these fields would always be null anyway. A value set through customizeCollection still wins; re-enabling authorship restores the fallback. A collection you define yourself for a Better Auth model must set authorship: false itself.
If your Payload 4 app already migrated on 0.40.0-next.1 or earlier, run payload migrate:create and read the diff. It drops the <table>_rels tables (columns path, users_id, …) that held createdBy/updatedBy for the Better Auth tables, unless something you added through customizeCollection also stores relationships there. See Atomic operations for the policy and concurrency guarantees.
Known gap
The plugin's admin screens (passkeys, two-factor, API keys) still use Payload 3's --theme-* CSS variables, which Payload 4 retires, so their styling is off. Sign-in, sessions and access control are unaffected.
Versioning
The next line was renumbered from 0.14.0-next.x to 0.40.0-next.x with the 0.14.0 release, so the two lines can never collide; pin 0.40.0-next.1 or later. For production, stay on latest until Payload 4.0 is stable. At that point the Payload 4 line becomes latest, and 0.14.x stays installable for Payload 3.
Work happens on the payload-4 branch. Report problems in an issue with "Payload 4" in the title.