v2.0.0-rc.3

The Miniflare docs now include a migration guide for upgrading from version 1.

Breaking Changes

• Mounts are no longer accessible by default via /<mount_name>. You must specify routes in wrangler.toml using the route/routes/miniflare.route/miniflare.routes options for them to be accessible. See 🔌 Multiple Workers for more details. This feature was inspired by multiflare, created by @dan-lee.
• All file-path-valued options are now resolved relative to the --root option
• Miniflare#dispatchFetch will now rewrite the request's URL/Host header to match the upstream URL if specified
• convertNodeRequest no longer accepts an upstream parameter, it now always uses the request's Host header

Features

• Make Request/Response bodys byte streams, allowing them to be read with bring-your-own-buffer readers
• Allow setting the wrangler.toml environment when mounting workers with the CLI. For example, --mount api=./api@dev mounts the worker in the ./api directory as api, using the dev environment in ./api/wrangler.toml.
• Allow setting the Durable Object script_name option via the CLI. For example, --do COUNTER=Counter@api binds the COUNTER Durable Object namespace using the Counter class exported by the mounted api worker.
• Update error message when attempting to access bindings via global in modules mode for Cloudflare Pages
• When the fetch_refuses_unknown_protocols compatibility flag isn't set, log a warning when attempting to use a protocol other than http or https
• The upstream URL is now validated on startup if specified

Fixes

• Copy webSocket when constructing a Response from an existing Response, closes issue #100, thanks @universse
• Allow constructing null body with empty-string, closes issue #101, thanks @PH4NTOMiki
• Remove ASCII whitespace from atob input, closes issue #104, thanks @dan-lee
• Remove keys limit from Durable Objects list() method, closes issue #105, thanks @vzaramel
• Allow Sec-WebSocket-Protocol header in WebSocket fetch, closes issue #106, thanks @f5io
• Fix uncaught rejection when closing server-sent events connection, closes issue #107, thanks @dan-lee
• Bump undici to 4.11.1, allowing Responses with null bodies to be cloned, closes issue #110, thanks @payellodevsupport
• Allow forbidden header mutation on Request/Response instances, closes cloudflare/wrangler2 issue #59, thanks @oliverjam
• Allow missing parent script with mounted workers
• Correctly handle attempting to read a key in a namespace that is also a key when using FileStorage, and throw when trying to write in this case (this is a limitation of Miniflare's file-system storage).
• When the fetch_refuses_unknown_protocols compatibility flag isn't set, correctly replace non-standard protocols (e.g. random://) with http:// in fetch.
• Remove types dependency on lib.webworker
• Incoming https requests will now have https URLs

v2.0.0-rc.2

Features

• Add structuredClone to the sandbox
• Copy --kv-persist, --cache-persist and --do-persist options to --mounts, so data is shared correctly
• Resolve mount-custom storage persistence options relative to mounted directory
• Add a more helpful error message on DurableObjectStorage#get deserialization failure due to Miniflare 1 data
• Add a more helpful error message on Cache#match deserialization failure due to Miniflare 1 data
• Add a more helpful error message when unable to find a matching module rule that suggests bundling npm packages

Fixes

• Bump undici to 4.10.2, closes issues #84 and #91, thanks @gzuidhof and @tranzium
• Remove Host and CF-Connecting-IP headers when fetching, closes issue #97, thanks @WalshyDev
• Allow file-system persisted keys to start with /, thanks @eidam for reporting this
• Setting an option to undefined now overrides that option in wrangler.toml like Miniflare 1
• When building mounted workers, set the current working directory to the mounted directory
• Respect the fetch_refuses_unknown_protocols compatibility flag in DurableObjectStub#fetch
• Default Response.redirect status to 302 instead of throwing
• Improve spec-compliance of WebSocket event constructors

Jest Fixes 🙁

• Fix importing miniflare in Jest when using the node environment, specifically fix WebSocketServer import and atob/btoa/AbortSignal globals
• Add Buffer to global in jest-environment-node, thanks @dan-lee for the PR
• Allow dynamic code generation in jest-environment-node for coverage, thanks @dan-lee for reporting this

v2.0.0-rc.1

Breaking Changes

• Changed the priority of bindings, so it matches Miniflare 1. The new order (from lowest to highest priority) is:
  1. Variables from wrangler.toml [vars]
  2. Variables from .env files
  3. WASM module bindings (--wasm, [wasm_modules])
  4. Custom bindings
• The result of dispatchScheduled will no longer include undefined if a module scheduled handler doesn't return a value

Features

• Added a custom Jest test environment for Miniflare. This allows you to run unit tests in the Miniflare sandbox, with isolated storage for each test. Install jest-environment-miniflare@next to get started and see 🤹 Jest Environment for more details.
• Added support for running multiple workers in the same Miniflare instance. See 🔌 Multiple Workers for more details.
• Added support for the Durable Object script_name option. See 📌 Durable Objects for more details.
• Added support for the new __STATIC_CONTENT_MANIFEST text module for using Workers Sites in modules mode
• Throw an error when a Durable Object fetch handler doesn't return a Response
• Added queueMicrotask to the sandbox
• Added the Miniflare#getCaches method for accessing the global caches outside workers
• Added back the sourceMap option to Miniflare
• Changed the default location for the update-check and cf.json files to inside node_modules
• Switched the CRON validation and scheduling package from node-cron to cron-schedule. This improves error messages for invalid CRON expressions, and removes a transitive dependency on moment-timezone, reducing the installation size by a further 5MB.

Fixes

• Allow any close code when a client closes a WebSocket connection. Closes issue #86, thanks @TimTinkers.
• Wait for worker response before opening WebSocket in client, closes issue #88, thanks @TimTinkers.
• Pass the --env flag to wrangler build when --wrangler-env is set for type = "webpack"/"rust" builds
• Set correct Host header with --upstream flag set
• Fixed memory leak in HTMLRewriter when passing non-ArrayBuffer(View) chunks
• Marked @miniflare/core and @miniflare/storage-memory as dependencies of @miniflare/durable-objects
• Removed ServiceWorkerGlobalScope#dispose() from global scope

v2.0.0-next.3

Fixes

• Remove Content-Length header from HTMLRewriter transformed Responses
• Update Content-Length header if set and live-reload is enabled
• Inject the live-reload script when there is no closing </body> tag. Closes issue #70, thanks @jed for reporting this, and @lukeed for the PR.
• Bump undici to 4.9.3, fixing iteration of Headers. Closes issue #64, thanks @Kikobeats for reporting this, and @lukeed for fixing this in undici.
• Added install-time check for minimum supported Node.js version. Thanks @lukeed for the PR.
• Updated build script to use ES module exports of dependencies where possible. Thanks @lukeed for the PR.

v2.0.0-next.2

Fixes

• Added support for the Response#encodeBody property. If this is omitted or set to auto, Responses with a Content-Encoding header that includes gzip, deflate or br will be automatically encoded. Closes issue #72, thanks @SupremeTechnopriest.
• Getters on Request/Response are now enumerable, and headers added to Request/Response instances after construction will now be retained if those instances are used to construct new Request/Responses. Closes issue #73, thanks @maraisr and @somebody1234.
• Variables defined in .env files now override those in wrangler.toml. Closes issue #75, thanks @payellodevsupport for the PR.
• http and https protocols are now required for WebSocket upgrades via fetch as per the workers runtime
• Miniflare-added CF-* headers are now included in the HTML error response

v2.0.0-next.1

Miniflare 2 has been completely redesigned from version 1 with 3 primary design goals:

1. 📚 Modular: Miniflare 2 splits Workers components (KV, Durable Objects, etc.) into separate packages (@miniflare/kv, @miniflare/durable-objects, etc.) that you can import on their own for testing.
2. ✨ Lightweight: Miniflare 1 included 122 third-party packages with a total install size of 88.3MB. Miniflare 2 reduces this to 24 packages and 11.5MB 🤯. This can probably be reduced further too.
3. ✅ Correct: Miniflare 2 more accurately replicates the quirks and thrown errors of the real Workers runtime, so you'll know before you deploy if things are going to break.

The docs will be updated over the next few weeks.

Notable Changes

• ✳️ Node.js 16.7.0 is now the minimum required version
• 🎲 Added support for crypto.randomUUID()
• 🔐 Added support for the NODE-ED25519 algorithm
• 📅 Added support for compatibility dates and flags: durable_object_fetch_requires_full_url, fetch_refuses_unknown_protocols, formdata_parser_supports_files
• 📚 Added a proper CommonJS module loader
• 🚪 Added Durable Object input and output gates, and write coalescing
• 🛑 Added the DurableObjectState#blockConcurrencyWhile(callback) method
• ⚡️ Added a live reload feature (--live-reload) that automatically refreshes your browser when your worker reloads
• 🗺 Automatically fetch the incoming Request#cf object from a trusted Cloudflare endpoint
• ✉️ Added support for sending/receiving binary WebSocket messages

Breaking Changes

• Node.js 16.7.0 is now the minimum required version. You should use the latest Node.js version if possible, as Cloudflare Workers use a very up-to-date version of V8. Consider using a Node.js version manager such as https://volta.sh/ or https://github.com/nvm-sh/nvm.

• Changed the storage format for Durable Objects and cached responses. If you're using file-system or Redis storage, you'll need to delete these directories/namespaces.

• Changed the Durable Object ID format to include a hash of the object name. Durable Object IDs generated in Miniflare 1 cannot be used with Miniflare 2.

• Removed support for the Durable Object script_name option. This was implemented incorrectly in Miniflare 1. It will be re-implemented correctly soon.

• Removed the non-standard DurableObjectStub#storage() method. To access Durable Object storage outside a worker, use the new Miniflare#getDurableObjectStorage(id) method, passing a DurableObjectId obtained from a stub.

• Renamed the --disable-cache/disableCache: true option to --no-cache/cache: false

• Renamed the --disable-updater option to --no-update-check

• When using the API, wrangler.toml, package.json and .env are now no longer automatically loaded from their default locations. To re-enable this behaviour, set these options to true:

  const mf = new Miniflare({
    wranglerConfigPath: true,
    packagePath: true,
    envPath: true,
  });

• Replaced the ConsoleLog class with the Log class from @miniflare/shared. You can construct this with a member from the LogLevel enum to control how much information is logged to the console:

  import { Miniflare } from "miniflare";
  import { Log, LogLevel } from "@miniflare/shared";
  
  const mf = new Miniflare({
    log: new Log(LogLevel.DEBUG),
  });

• Load WASM bindings from the standard wasm_modules wrangler.toml key instead of miniflare.wasm_bindings.

  # wrangler.toml
  [miniflare]
  wasm_bindings = [
    { name = "MODULE1", path="module1.wasm" },
    { name = "MODULE2", path="module2.wasm" }
  ]

  ...should now be...

  # wrangler.toml
  [wasm_modules]
  MODULE1 = "module1.wasm"
  MODULE2 = "module2.wasm"

• Replaced the Miniflare#reloadOptions() method with the Miniflare#reload() and Miniflare#setOptions({ ... }) methods. reload() will reload options from wrangler.toml (useful if not watching), and setOptions() accepts the same options object as the new Miniflare constructor, applies those options, then reloads the worker.

• Miniflare#createServer() now always returns a Promise which you must await to get a http.Server/https.Server instance. You may want to check out the new Miniflare#startServer() method which automatically starts a server using the configured host and port.

• Miniflare no longer includes CommonJS exports. You must use ES modules. If you need to import miniflare in a CommonJS file, use dynamic import: const { Miniflare } = await import("miniflare").

• Redis support is no longer included by default. If you're persisting KV, Durable Objects or cached responses in Redis, you must install the @miniflare/storage-redis optional peer dependency.

• Replaced how Miniflare sanitises file paths for file-system storage so namespace separators (/, \, : and |) now create new directories.

Features and Fixes

Cache:

• Added support for cf.cacheKey, cf.cacheTtl and cf.cacheTtlByStatus on Request. Closes issue #37, thanks @cdloh.
• Added the CF-Cache-Status: HIT header to matched Responses
• Log warning when trying to use cache with workers_dev = true in wrangler.toml. Cache operations are a no-op on workers.dev subdomains.
• Throw errors when trying to cache Web Socket, non-GET, 206 Partial Content, or Vary: * responses
• Throw an error when trying to open a cache with a name longer than 1024 characters

CLI:

• Separated command line options into sections
• Validate types of all command line options

Builds:

• When running your worker's build script, Miniflare will set the environment variable MINIFLARE=1. Closes issue #65, thanks @maraisr.
• Added an alias, -B, for the --build-command option
• Multiple build watch paths can now be specified. If any of them change, your worker will rebuild and reload.
• Fixed an issue where workers would not rebuild if the build watch path started with ./. Closes issue #53, thanks @janat08.

Standards:

• Added support for crypto.randomUUID()
• Added support for the NODE-ED25519 algorithm to crypto.subtle.sign() and crypto.subtle.verify()
• Throw an error when attempting to create a new TextDecoder with a non-UTF-8 encoding
• Throw errors when attempting to use FetchEvent/ScheduledEvent methods with incorrectly bound this
• Throw errors when attempting to call respondWith() twice, or after the fetch handler has finished executing synchronously. Closes issue #63, thanks @Kikobeats.
• Added support for the unhandledrejection and rejectionhandled events
• Throw an error (with a suggested fix) when trying to access an env binding globally in modules mode
• Throw errors when trying to use addEventListener(), removeEventListener() and dispatchEvent() globals in modules mode
• Split the FetchError: No fetch handler responded and unable to proxy request to upstream? error into more specific errors with suggested fixes
• Added the non-standard Headers#getAll() method. This can only be used with the Set-Cookie header.
• Switch to a more spec-compliant fetch implementation, and get crypto, EventTarget and Web Streams from Node.js. Closes issues #56 and #59, thanks @jasnell, @jonathannorris and @SupremeTechnopriest.
• Throw an error when attempting to construct a WebSocket response with a status other than 101
• Throw an error when attempting to clone a WebSocket response
• Added support for the non-standard ReadableStreamBYOBReader#readAtLeast(size, buffer) method
• Include File in the Miniflare sandbox. Closes issue #66, thanks @tranzium.

Bindings:

• Added --global KEY=VALUE/globals: { KEY: "value" } option for binding arbitrary values to the global scope. This behaves exactly like the --binding/bindings: { ... } option, but always binds to the global scope, even in modules mode.
• Added a new global variable MINIFLARE to the Miniflare sandbox, which will always have the value true when your script is running within Miniflare
• Miniflare now stringifies all environment variables from wrangler.toml. Closes issue #50, thanks @ozburo.

Core:

• Added support for compatibility dates and flags, specifically the flags durable_object_fetch_requires_full_url, fetch_refuses_unknown_protocols, formdata_parser_supports_files are now supported. This feature is exposed under the --compat-date and --compat-flag CLI options, in addition to the standard keys in wrangler.toml. Closes issue #48, thanks @PaganMuffin.
• Added a proper CommonJS module loader. Workers built with Webpack will be more likely to work with Miniflare now. Closes issue #44, thanks [@TimTinkers](https://github....

v1.4.1

Fixes

• Fixed linking of modules with cyclic imports, allowing new Rust workers to be run with Miniflare. Closes issue #41, thanks @nuvanti.
• Fixed handling of ArrayBufferViews as Response bodies

v1.4.0

Features

• Added Event and EventTarget to the sandbox. The global scope and WebSocket now inherit from EventTarget so removeEventListener is now supported. Closes issue #18, thanks @jayphelps.
• Added workers' uncompressed size to logs, closes issue #23, thanks @ItsWendell
• Switch to lighter dependencies, thanks @lukeed. There's still lots of work to do here for the next major release.

Fixes

• Require the GET method for WebSocket upgrades, closes issue #25, thanks @ItsWendell
• Added WebSocket to the sandbox, closes issue #30, thanks @ItsWendell. Note you still need to use WebSocketPair and fetch to set up WebSocket connections. See ✉️ WebSockets for more details.
• Fixed caching with URL request keys, closes issue #33, thanks @TimTinkers
• Disable the watcher whilst rebuilding, closes issue #34, thanks @TimTinkers

v1.3.3

Features

• Added an option to disable default and named caches. When disabled, the caches will still be available in the sandbox, they just won't cache anything. Thanks @frandiox for the suggestion. See ✨ Cache for more details.
• Added the corresponding wrangler.toml key for the --disable-updater flag: miniflare.disable_updater

Fixes

• Fixed the package.json file path the update checker checked against

v1.3.2

Features

• Responses are now streamed when using the built-in HTTP(S) server
• Return values of Durable Object transaction closures are now propagated as the return value of the transaction call

Fixes

• Upgraded html-rewriter-wasm to version 0.3.2, fixing async handler support, closes html-rewriter-wasm issue #1