miniflare
4.20260730.0 · 30 Jul 2026MIT44M / weekRepositoryHomepagenpmAtom feed
Where each line stands
Plan an upgrade- 4.x4.20260730.0No known advisoryLatest line
- 3.x3.20250718.3Safe from 3.20231030.2To 4.20260730.0
- 2.x2.14.4No known advisoryTo 4.20260730.0
- 1.x1.4.1No known advisoryTo 4.20260730.0
- 0.x0.20230908.0No known advisoryTo 4.20260730.0
Latest releases
All 300 releases4.20260730.0
30 Jul 2026Add JSON output to
/cdn-cgi/handler/emailThe
/cdn-cgi/handler/emailendpoint now accepts?format=jsonto return the email handler result as JSON, including its outcome, rejection reason, forwarded messages, and replies. Requests withoutformat=jsonstill return the existing text outcome for backward compatibility.Fix the local Images binding transform (
env.IMAGES.input(...).transform(...)) ignoring thefit,gravity, andbackgroundoptions. Previously, local dev always letterboxed transformed images with black bars regardless of the options passed in. Local dev now respectsfit,gravity, andbackground, matching production Images binding behavior.Disable the keep-alive timeout on the loopback server
The loopback server (which serves custom service bindings,
@cloudflare/vite-plugin's module transport, and other workerd → Node callbacks) used Node's defaultserver.keepAliveTimeoutof 5 seconds. workerd pools and reuses connections to the loopback server, so Node closing an idle pooled socket raced with workerd sending the next request on it, making that request fail withNetwork connection lost. The failure is probabilistic and load-dependent; under@cloudflare/vite-pluginwith a large SSR module graph and a cold optimizer cache (thousands offetchModulecalls with multi-second idle gaps between bursts), it broke most dev sessions. Disable the idle keep-alive timeout on the loopback server, mirroring the undici pools used for dispatch in the opposite direction.
Minor Changes
Add JSON output to
/cdn-cgi/handler/emailThe
/cdn-cgi/handler/emailendpoint now accepts?format=jsonto return the email handler result as JSON, including its outcome, rejection reason, forwarded messages, and replies. Requests withoutformat=jsonstill return the existing text outcome for backward compatibility.
Patch Changes
Fix the local Images binding transform (
env.IMAGES.input(...).transform(...)) ignoring thefit,gravity, andbackgroundoptions. Previously, local dev always letterboxed transformed images with black bars regardless of the options passed in. Local dev now respectsfit,gravity, andbackground, matching production Images binding behavior.Disable the keep-alive timeout on the loopback server
The loopback server (which serves custom service bindings,
@cloudflare/vite-plugin's module transport, and other workerd → Node callbacks) used Node's defaultserver.keepAliveTimeoutof 5 seconds. workerd pools and reuses connections to the loopback server, so Node closing an idle pooled socket raced with workerd sending the next request on it, making that request fail withNetwork connection lost. The failure is probabilistic and load-dependent; under@cloudflare/vite-pluginwith a large SSR module graph and a cold optimizer cache (thousands offetchModulecalls with multi-second idle gaps between bursts), it broke most dev sessions. Disable the idle keep-alive timeout on the loopback server, mirroring the undici pools used for dispatch in the opposite direction.Capture Workflows invocations in local observability
When local observability is enabled, the Workflows engine service is now attached to the trace collector (like every user worker), so workflow runs show up in the Local Explorer's Observability view attributed to the workflow. Previously the engine ran outside the per-user-worker tail wiring, so workflow invocations left no traces, spans, or logs in the local store.
4.20260722.1
28 Jul 2026Support passing V8 flags to
workerdvia theMINIFLARE_WORKERD_V8_FLAGSenvironment variableThe generated
workerdconfig already supportsv8Flags, but Miniflare never populated it, so the runtime always ran with V8's default heap limit (~1.4 GB). Large dev applications (e.g. big SSR module graphs under@cloudflare/vite-plugin, where each server-file edit grows the runner isolate's heap) can reach that limit, at which pointworkerdaborts withV8 fatal error; location = Reached heap limitand every subsequentdispatchFetch()fails withfetch faileduntil the dev server is manually restarted.Setting e.g.
MINIFLARE_WORKERD_V8_FLAGS="--max-old-space-size=4096"raises the limit and keeps long dev sessions alive. The variable follows the same space-separated format asMINIFLARE_WORKERD_AUTOGATES.Add a local S3-compatible API for R2 buckets at
/cdn-cgi/local/r2/s3/<bucket-id>, where<bucket-id>is the ID the bucket is configured with in ther2BucketsoptionBuckets configured with
s3Credentials: { accessKeyId, secretAccessKey }inr2Bucketsare served over an S3-compatible HTTP API, authenticated with AWS Signature Version 4 (bothAuthorizationheader and presigned URL query authentication). Supported operations: GetObject, HeadObject, PutObject, CopyObject, DeleteObject, DeleteObjects, ListObjects, ListObjectsV2, HeadBucket, ListBuckets, CreateMultipartUpload, UploadPart, UploadPartCopy, CompleteMultipartUpload, and AbortMultipartUpload. Status codes, error responses, and unsupported-header screening mirror R2's S3 endpoint, including its static responses for bucket-configuration reads and its named errors for unimplemented operations.Support
connect()on remote VPC Network and VPC Service bindings in local developmentRemote VPC Network and VPC Service bindings previously only supported HTTP and JSRPC, so calling
binding.connect(address)against a private TCP service (for example a database) failed in local dev withIncoming CONNECT on a worker not supported. Raw TCP connections through remote VPC Network and VPC Service bindings now work in local development.This feature is experimental. Existing HTTP and JSRPC usage of remote VPC Network and VPC Service bindings is unaffected, and no new configuration is required.
Minor Changes
Support passing V8 flags to
workerdvia theMINIFLARE_WORKERD_V8_FLAGSenvironment variableThe generated
workerdconfig already supportsv8Flags, but Miniflare never populated it, so the runtime always ran with V8's default heap limit (~1.4 GB). Large dev applications (e.g. big SSR module graphs under@cloudflare/vite-plugin, where each server-file edit grows the runner isolate's heap) can reach that limit, at which pointworkerdaborts withV8 fatal error; location = Reached heap limitand every subsequentdispatchFetch()fails withfetch faileduntil the dev server is manually restarted.Setting e.g.
MINIFLARE_WORKERD_V8_FLAGS="--max-old-space-size=4096"raises the limit and keeps long dev sessions alive. The variable follows the same space-separated format asMINIFLARE_WORKERD_AUTOGATES.Add a local S3-compatible API for R2 buckets at
/cdn-cgi/local/r2/s3/<bucket-id>, where<bucket-id>is the ID the bucket is configured with in ther2BucketsoptionBuckets configured with
s3Credentials: { accessKeyId, secretAccessKey }inr2Bucketsare served over an S3-compatible HTTP API, authenticated with AWS Signature Version 4 (bothAuthorizationheader and presigned URL query authentication). Supported operations: GetObject, HeadObject, PutObject, CopyObject, DeleteObject, DeleteObjects, ListObjects, ListObjectsV2, HeadBucket, ListBuckets, CreateMultipartUpload, UploadPart, UploadPartCopy, CompleteMultipartUpload, and AbortMultipartUpload. Status codes, error responses, and unsupported-header screening mirror R2's S3 endpoint, including its static responses for bucket-configuration reads and its named errors for unimplemented operations.Support
connect()on remote VPC Network and VPC Service bindings in local developmentRemote VPC Network and VPC Service bindings previously only supported HTTP and JSRPC, so calling
binding.connect(address)against a private TCP service (for example a database) failed in local dev withIncoming CONNECT on a worker not supported. Raw TCP connections through remote VPC Network and VPC Service bindings now work in local development.This feature is experimental. Existing HTTP and JSRPC usage of remote VPC Network and VPC Service bindings is unaffected, and no new configuration is required.
Patch Changes
Fix
getWithMetadatadropping metadata for falsy KV valuesKVNamespace.getWithMetadatareturnednullmetadata whenever the stored value was falsy — an empty string or"0"— because the metadata branch was guarded by a truthiness check on the value. The guard now checks fornullexplicitly, so metadata is preserved for empty-string and"0"values while genuinely missing keys still returnnull.Hide the workerd console window on Windows when the parent process has no console. Spawning workerd without
windowsHide: truecaused Windows Terminal to open a visible, focus-stealing window for background or detached parents (for example Astro'sastro dev --background).
4.20260722.0
23 Jul 2026Add local-dev observability
wrangler devand the Vite plugin now capture a trace for every local Worker invocation - spans, logs, andconsole.*output, including requests that cross worker or Durable Object boundaries.You can explore this data two ways:
While this is in testing it's off by default; set
X_LOCAL_OBSERVABILITY=trueto turn it on. It will be on by default in the public release.Fix incorrect byte limit reported in the local Queues batch-size error
When a queue batch exceeded the maximum batch byte size in local dev, the thrown
PayloadTooLargeErrorhardcoded the limit as256000, even though the value actually enforced is288000bytes ((256 + 32) * 1000). The message now interpolates the real limit, consistent with the other Queue limit errors in the same file.Recover local development after the Workers runtime crashes
Previously, an unexpected workerd crash left Miniflare running but unable to serve subsequent requests. Miniflare now restarts workerd after post-startup crashes, while continuing to surface startup crashes as fatal errors.
The Cloudflare Vite plugin also restarts the Vite development server after workerd recovers so its environments, hot channels, and module runners are recreated.
Minor Changes
Add local-dev observability
wrangler devand the Vite plugin now capture a trace for every local Worker invocation - spans, logs, andconsole.*output, including requests that cross worker or Durable Object boundaries.You can explore this data two ways:
A new Observability tab in the Local Explorer, with a Traces view (recent invocations, an inline timeline waterfall, and filters) and an Events view.
A read-only SQL endpoint at
/cdn-cgi/explorer/api/local/observability/query, discoverable via the Local Explorer's OpenAPI document, so coding agents and tools can query the samespansandlogstables.
While this is in testing it's off by default; set
X_LOCAL_OBSERVABILITY=trueto turn it on. It will be on by default in the public release.
Patch Changes
Fix incorrect byte limit reported in the local Queues batch-size error
When a queue batch exceeded the maximum batch byte size in local dev, the thrown
PayloadTooLargeErrorhardcoded the limit as256000, even though the value actually enforced is288000bytes ((256 + 32) * 1000). The message now interpolates the real limit, consistent with the other Queue limit errors in the same file.Recover local development after the Workers runtime crashes
Previously, an unexpected workerd crash left Miniflare running but unable to serve subsequent requests. Miniflare now restarts workerd after post-startup crashes, while continuing to surface startup crashes as fatal errors.
The Cloudflare Vite plugin also restarts the Vite development server after workerd recovers so its environments, hot channels, and module runners are recreated.
Dependency tracking · free for 3 projects
Know when your own dependencies move
miniflare published 80 releases in the last 12 months. inlinr folds the routine ones into a line and keeps the few that need you.
Advisories reach you
An email when a critical or high advisory affects a project, before the next install.
Upgrades checked first
Peer ranges, Node, ESM-only and types changes read before you bump.
Only what matters
Majors and breaking notes stay; patches and sibling bumps fold into one line.
Reading releases, release notes and advisories…
Registry facts last checked 5 Nov 2026. Releases and advisories last read 5 Nov 2026.