RFC: Plugin for edge runtime compatibility config options

[DanRibbens]

Written with AI

RFC: Maintained runtime compatibility defaults for Payload

• Status: Draft for discussion
• Working package name: @payloadcms/plugin-edge or @payloadcms/plugin-cloudflare
• Prototype: Cloudflare plugin draft #19197

Motivation

We keep making tweaks for Cloudflare compatibility. Adding them to the template helps new projects, but existing users do not inherit those changes simply by updating Payload. They must discover the fix and copy the required configuration into their application.

Password-hashing PR #19070 is a concrete example: after updating, Workers users must also add auth.passwordHashIterations: 100000 to their config. With a compatibility plugin already installed and enabled, updating to a release containing that default would apply it automatically. Users could explicitly override the plugin's defaults to opt out of individual changes.

The main benefit is an upgrade path for maintained compatibility defaults. Templates would install the integration once; package updates would deliver subsequent Payload-side adjustments.

Evidence from the template history

The history of templates/with-cloudflare-d1 shows repeated compatibility changes since the initial D1/R2 integration #12537:

Problem	Change and references
Password hashing exceeds the Workers iteration limit, preventing user creation	Issue #18274; configurable iterations #19070, with 3.x backport #19074. Earlier proposals: #18276 and #18461.
Default logging fails on unsupported filesystem APIs	Issue #14849; #15752 adds a console-based logger directly to the template.
Image-editing controls require unavailable image processing	#12537 introduces crop: false and focalPoint: false; #17577 documents the image-resizing limitation.
Local development unexpectedly connects to the remote database	Issue #14041; #14063 changes binding selection and pins Wrangler.
CLI detection does not cover payload run	#15098 changes how the template recognizes Payload CLI execution.
Bundling Wrangler breaks template styling	Issue #13989; #14067 adds webpackIgnore to the dynamic import.
OpenNext needs special handling for packages containing Workers-specific code	#15094 adds serverExternalPackages for jose and pg-cloudflare, referencing #14656 and #14181.
Node-only migration tooling enters the production bundle	Issue #16470; #17577 works around the build failure by selecting Webpack. It also references broader template fixes in #17393 and the config-version mismatch reported in #17195.

#15752 also adds documentation recommending native fetch for undici diagnostic-channel errors. Its diff does not add the documented skipSafeFetch setting to the Media collection—another example of configuration knowledge becoming scattered. This is a documented workaround, not evidence that the fetch issue was fully fixed.

Not every row belongs in a Payload plugin. Build flags, framework configuration, and bindings may require separate integration helpers or template changes. The history establishes the recurring maintenance problem, not a promise that one plugin resolves every case.

Proposal

Provide an opt-in plugin that applies maintained defaults for a selected environment, preserves explicit application settings, and reports unsupported combinations.

The MongoDB adapter's existing compatibilityOptions provides a useful precedent: environment-specific presets group settings that developers otherwise have to discover individually.

We need more planning and thought about what we ship. The public API should not necessarily be limited to Cloudflare. A generic Workers or edge plugin could accept an environment-specific profile:

import { compatibilityOptions, edgeRuntimePlugin } from '@payloadcms/plugin-edge'
import { buildConfig } from 'payload'

export default buildConfig({
  plugins: [
    edgeRuntimePlugin({
      compatibilityOptions: compatibilityOptions.cloudflareWorkers,
    }),
  ],
})

Names and profile structure are illustrative. Cloudflare would be the first candidate; this does not imply support for other edge platforms. We should compare another concrete environment before committing to a shared abstraction. “Runtime” may also be a better name than “edge” or “Workers.”

Behavior and boundaries

Configuration precedence should be:

1. Explicit application configuration.
2. Selected compatibility defaults.
3. Payload's normal defaults.

A plugin update can therefore fix compatibility without requiring a config edit, while an explicit setting remains an opt-out. An override that violates a hard runtime constraint should produce an actionable error rather than be silently replaced.

Initial candidates are password-hashing defaults, compatible logging, and upload defaults informed by configured image-processing capabilities. The plugin should account for compatible remote transformers rather than assume every edge deployment lacks image processing. Preserve application fields, including alternative text, and verify keyboard, focus, and accessible-control behavior when rendered UI changes.

Database and storage selection remain explicit. The plugin should not automatically select D1/R2, detect the runtime and change behavior, or disable security protections. Prefer core or adapter fixes where they remove the need for a workaround. Templates remain responsible for deployment scaffolding outside the plugin's reach.

Security and upgrade policy

• Password hashing: Keep Payload's OWASP-aligned 600,000 PBKDF2-SHA256 default outside profiles requiring a lower count. The Cloudflare prototype's 100,000 setting makes each offline guess roughly six times cheaper for otherwise identical parameters. Applying the setting automatically does not convert existing hashes: migration may still require password resets or a capable runtime. Document rollback and mixed-version limitations, and keep settings consistent across deployments sharing a database.
• Remote fetching: Do not automatically bypass Payload's SSRF-filtering fetch. Any native-fetch option needs explicit opt-in and must preserve collection policies. Production networking assumptions may not hold locally or with private-network integrations.
• Changing presets: Automatic delivery is the benefit, but observable changes still need a release policy. Assess changes to security, persisted data, and feature availability under normal compatibility guarantees; do not classify every preset adjustment as a harmless defaults update.

Shipping and validation

A new package needs its initial public npm publication and the release permissions or trusted-publishing configuration required by the existing release process. Agree on the name before publishing the prototype.

Register the package in build scripts, TypeScript references, release publishing and packing lists, workspace lockfiles, PR scopes, and applicable CI discovery or matrices. Coordinate template versions with the first published release containing the plugin and required core APIs.

Before declaring a profile supported, test defaults and overrides, validation after other integrations have configured collections, actual target-runtime execution, authentication and migration, storage/image processing, and a representative template build and deployment. Include browser/accessibility verification when UI changes. Node-only unit tests and successful package discovery in CI are insufficient evidence of runtime support.

Decisions still needed

1. Scope and naming: Cloudflare-specific plugin or shared runtime machinery with environment profiles? Which behaviors actually generalize?
2. Profile API: Plain objects, opaque profiles, or factories? Which defaults and opt-outs should the initial release expose?
3. Lifecycle: When can defaults and validation see collections, storage, and transformers added by other integrations?
4. Support contract: Which runtime versions or compatibility dates do profiles cover, and what release policy governs changes? Should the first release include 3.x?

The alternatives are to keep copying template changes, export static config presets without a plugin, or add runtime targeting to core. A plugin is useful if it makes compatibility fixes reach existing applications through routine updates while keeping explicit overrides and a clear support contract.