●Change8

Migrating to Cloudflare Workers miniflare@5.20260730.0-alpha

Version miniflare@5.20260730.0-alpha introduces 14 breaking changes. This guide details how to update your code.

Released: 7/31/2026

14
Breaking Changes
9
Migration Steps
44
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

Miniflare.unsafeGetPersistPaths()kvPersistr2Persistd1PersistcachePersistdurableObjectsPersistworkflowsPersistsecretsStorePersistanalyticsEngineDatasetsPersiststreamPersistimagesPersisthelloWorldPersistcacheWarnUsagefetchMockcreateFetchMockhttpsKeyPathhttpsCertPathliveReload/cdn-cgi/mf/reloadmigrateDatabase()handleRuntimeStdiostructuredWorkerdLogsunsafeStickyBlobswrappedBindingscontainerEngineformatZodError_forceColour/cdn-cgi/platform-proxy/cdn-cgi/local/platform-proxy/cdn-cgi/handler/scheduled/cdn-cgi/local/scheduled/cdn-cgi/handler/email/cdn-cgi/local/email/cdn-cgi/explorer/*/cdn-cgi/local/explorer/*/cdn-cgi/mf/scheduled/cdn-cgi/mf/stream/*/__cf_local/stream/*/cdn-cgi/mf/imagedelivery/*/__cf_local/imagedelivery/*maxRetiresQueueConsumerOptionsSchemaminiflare CLI binarybootstrap.js

Breaking Changes

●Issue #1

The per-resource persistence options (`kvPersist`, `r2Persist`, `d1Persist`, `cachePersist`, `durableObjectsPersist`, `workflowsPersist`, `secretsStorePersist`, `analyticsEngineDatasetsPersist`, `streamPersist`, `imagesPersist`, and `helloWorldPersist`) have been removed. Use the new `resourcePersistencePath` option instead. The `Miniflare.unsafeGetPersistPaths()` method has also been removed.

●Issue #2

The `cacheWarnUsage` Worker option has been removed.

●Issue #3

The `fetchMock` option and `createFetchMock` export have been removed.

●Issue #4

The `httpsKeyPath` and `httpsCertPath` options have been removed. To use a custom certificate, read the files and pass their contents via the existing `httpsKey` and `httpsCert` options.

●Issue #5

The built-in live reload mechanism has been removed, including the `/cdn-cgi/mf/reload` endpoint, the `liveReload` option, and automatic script injection. Use Wrangler or the Vite plugin for live reload.

●Issue #6

The `migrateDatabase()` helper for migrating Miniflare v2/early-v3 storage has been removed.

●Issue #7

The `handleRuntimeStdio` and `structuredWorkerdLogs` options have been removed. Structured logging is now always enabled, and logs are handled via `handleStructuredLogs` or written to the console by default.

●Issue #8

The `unsafeStickyBlobs` option has been removed. Blobs are now always cleaned up as expected.

●Issue #9

The `wrappedBindings` option has been removed.

●Issue #10

The `containerEngine` option has moved from a per-worker option to a top-level Miniflare option.

●Issue #11

The `formatZodError` and `_forceColour` helpers are no longer exported from `miniflare`; they are now exported from `@cloudflare/workers-utils`.

●Issue #12

Miniflare-internal endpoints have moved to new paths to avoid collision with production `/cdn-cgi` routes. The new paths are: `/cdn-cgi/local/platform-proxy`, `/cdn-cgi/local/scheduled`, `/cdn-cgi/local/email`, `/cdn-cgi/local/explorer/*`, `/__cf_local/stream/*`, and `/__cf_local/imagedelivery/*`. The `/cdn-cgi/mf/scheduled` endpoint has been removed.

●Issue #13

The deprecated `maxRetires` typo alias in Queue consumer options has been removed. Use `maxRetries` instead.

●Issue #14

The dummy CLI binary (`miniflare` bin entry and `bootstrap.js` stub) has been removed.

Migration Steps

  1. 1
    Rename `defaultPersistRoot` to `resourcePersistencePath`.
  2. 2
    Rename `defaultProjectTmpPath` to `resourceTmpPath`.
  3. 3
    If using custom certificates, read the key and certificate files and pass their contents via the `httpsKey` and `httpsCert` options instead of `httpsKeyPath` and `httpsCertPath`.
  4. 4
    If you were using the live reload mechanism, migrate to using Wrangler or the Vite plugin for live reload functionality.
  5. 5
    If you were using the `handleRuntimeStdio` option, migrate to using `handleStructuredLogs` or rely on the default console logging.
  6. 6
    If you were configuring `containerEngine` per worker, move it to a top-level Miniflare option.
  7. 7
    If you were importing `formatZodError` or `_forceColour` from `miniflare`, import them from `@cloudflare/workers-utils` instead.
  8. 8
    Update any references to the old Miniflare-internal endpoint paths to their new locations (e.g., `/cdn-cgi/platform-proxy` to `/cdn-cgi/local/platform-proxy`). Note that Wrangler and the Vite plugin will provide transparent rewrites for these.
  9. 9
    Replace any usage of the `maxRetires` option with `maxRetries`.

Release Summary

This release significantly refactors Miniflare, removing numerous deprecated options and endpoints for improved consistency and clarity. Key changes include consolidating persistence options, removing live reload, and updating internal endpoint paths.

Need More Details?

View the full release notes and all changes for Cloudflare Workers miniflare@5.20260730.0-alpha.

View Full Changelog