Miniflare Versions Save

Fixes

• Trust CA root certificates on Windows and NODE_EXTRA_CA_CERTS (https://github.com/cloudflare/miniflare/pull/587)
• Make process exits/server stops more aggressive to prevent test hangs (https://github.com/cloudflare/miniflare/pull/590)

Miniflare v3 now uses workerd, the open-source Cloudflare Workers runtime. This is the same runtime that's deployed on Cloudflare’s network, giving bug-for-bug compatibility and practically eliminating behavior mismatches. Refer to the Miniflare v3 and Wrangler v3 announcements for more information.

Missing Features

Several features from Miniflare v2 are not supported in Miniflare v3's initial release. However, they are on the roadmap, and will be added back soon:

• Step-through debugging
• Automatically triggering scheduled events via CRON schedules, or manually triggering them via /.mf/scheduled or /cdn-cgi/mf/scheduled (manually triggering events is supported via the --test-scheduled Wrangler flag and visiting /__scheduled)
• Starting an HTTPS server
• Mocking outbound fetch() requests
• The get{Bindings,KVNamespace,R2Bucket,Caches,DurableObjectNamespace}() methods

CLI Changes

Miniflare v3 no longer includes a standalone CLI. To get the same functionality, you will need to switch over to Wrangler. Wrangler v3 uses Miniflare v3 by default. To start a local development server, run:

$ npx wrangler@3 dev

If there are features from the Miniflare CLI you would like to see in Wrangler, please open an issue on GitHub.

API Changes

We have tried to keep Miniflare v3's API close to Miniflare v2 where possible, but many options and methods have been removed or changed with the switch to the open-source workerd runtime. See the 📚 GitHub README for the new API docs, and the ⬆️ Migration Guide for the full list of removals and changes.

Features

• Implement a new underlying storage system, using SQLite for metadata, and a separate file-system/in-memory backed blob store supporting streamed, ranged reads. Note, previously persisted data is incompatible with this system and must be deleted. (#555, #562, #563, #565)
• Add support for R2 multipart uploads (#565)
• Add support for R2 multipart, weak, and wildcard ETags (#575)
• Add support for Queues (#566)
• Add stub CLI recommending wrangler dev (#570)
• Add support for specifying custom upstreams (#568)

Fixes

• Allow multiple Miniflare instances in different processes/worker-threads to start in parallel with port: 0 (#575)
• Allow node: and cloudflare: modules to be used with modules: true option (#569)
• Correctly source-map service worker type scripts (#572)

Features

• Add support for the Ed25519 algorithm and mark X448/Ed448 algorithms as unsupported. Thanks @panva for jose's comprehensive test suite.
• Add ExecutionContext as a global value to Miniflare's unit testing environments' global types. Miniflare injects the ExecutionContext class into testing environments, so they can be constructed and passed to imported module event handlers. This change ensures new ExecutionContext() isn't a type error.
• Allow wrangler.toml build.watch_dir to be an array of directories. Thanks @sj-e2digital for the PR.

Fixes

• Ensure queue consumers are registered when using Miniflare's unit testing environments.
• Fix crash when calling Miniflare#reload() with queue consumers set. Closes issue #560, thanks @calebmer.
• Add @miniflare/core as a dependency of @miniflare/r2. Closes issue #559, thanks @calebmer.
• Update @miniflare/d1 README with new API

Features

• Add native support for Windows (#551)
• Add support for routing to multiple Workers (#520)
• Add support for logging incoming HTTP requests (#550)
• Improve support for newer R2 features (#524)
  • Add support for deleting multiple keys in R2Bucket#delete()
  • Add support for ranged-gets with a Range header in R2Bucket#get()
  • Add support for R2Bucket#list() startAfter option
  • Add support for sha* checksums in R2Bucket#put() and return from R2Bucket#{get,head}
  • Add support for conditional R2Bucket#put()
  • Add support for secondsGranularity option in R2Conditionals
  • Add validation for customMetadata size to R2Bucket#put()
  • Return range information from R2Bucket#head()

Fixes

• Use UTC timezone when checking if compatibility date is in the future (#558)

Features

• Add support for DurableObjectNamespace#jurisdiction() method. Note the passed jurisdiction is validated but otherwise ignored. IDs generated by sub-namespaces in different jurisdictions will be the same. Thanks @DaniFoldi for the PR.
• Add support for the non-standard crypto.subtle.timingSafeEqual() function. Thanks @DaniFoldi for the PR.
• Remove requirement for experimental compatibility flag alongside nodejs_compat to use node:assert, node:buffer and node:util modules. Closes issue #547, thanks @Skye-31 and @DaniFoldi for the PR.

Fixes

• Fix binding of ?N parameters in D1 prepared statements. Closes issues #504, #526, cloudflare/workers-sdk#2811 and cloudflare/workers-sdk#2887. Thanks @ruslantalpa and @maurerbot.
• Fix cloning of Responses constructed with byte streams. Notably, byte streams are returned from lots of Workers runtime APIs (e.g. KV, R2) to support BYOB reads. Closes issue #527, thanks @cwkang1998.
• Copy Content-Length from Request/Response body streams when constructing a new Request/Response or calling fetch. Closes issue #522, thanks @notorca.

Fixes

• Fix detection of read-only D1 SQL statements in Jest. Closes issue #529, thanks @jschlesser for the PR.

Fixes

• Use SIGINT when terminating runtime process to avoid gracefully draining HTTP connections, and immediately dispose()/setOptions()

Features

• Add support for D1 via the d1Databases option (#519)

  Note instead of providing a D1Database binding with the database name like Miniflare 2, we now provide a regular Fetcher service binding like the real runtime.

• Add support for the durableObjectsPersist option (#517)

• Log causes of errors returned with the MF-Experimental-Error-Stack header (#519)

• Propagate errors returned with the MF-Experimental-Error-Stack header through dispatchFetch() (assuming the Accept header prevents the text/html-typed pretty-error page being returned) (#519)

Fixes

• Strip MF-Custom-Service header from requests to custom service bindings, closes #475 (#515)
• Strip restricted headers from requests back from workerd to Miniflare, closes #476 (#515)
• Allow clean exit when using the Cache API, closes #481 (#515)
• Preserve URL passed to Miniflare#dispatchFetch() and custom service binding fetch(), closes #488 (#515)
• Bump better-sqlite3 to 8.1.0 allowing installation on Node 19, closes #518 (#521)

⚠️ Security Update

Fixes

• Bump undici to 5.20.0, addressing GHSA-5r9g-qh6m-jxff and GHSA-r6ch-mqf9-qc9w. Thanks @WalshyDev and @Cherry for the PR.
• Ensure global uniqueness of Durable Objects across mounts. Previously, it was possible to have multiple Durable Object instances with the same ID if they were created from different mounts. Closes #461, thanks @Finistere.
• Return a R2MultipartUpload instead of a Promise<R2MultipartUpload> from R2Bucket#resumeMultipartUpload(). Thanks @notorca for the PR.
• Copy known-lengths from FixedLengthStreams and Request/Response body streams when calling ReadableStream#tee(). Closes issue #506, thanks @notorca.