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

v1.3.1

Fixes

• Upgraded html-rewriter-wasm to version 0.3.1, fixing the return type of Element.attributes

v1.3.0

Features

• Switched to a lol-html-based WebAssembly implementation of HTMLRewriter for a more accurate simulation of the real Workers environment. See 📄 HTMLRewriter for more details.
• Added HTTPS support for local development, thanks @RichiCoder1 for the suggestion (#12). See 💻 Using the CLI and 🧰 Using the API for more details.
• When using the CLI, the --watch flag is now assumed if --build-watch-path is set, thanks @evanderkoogh for the PR (#8)
• Added source maps to CommonJS module transformation

Fixes

• Switched to real values for the cf property, thanks @chase for the PR (#11)
• Upgraded the TOML parser to support dotted keys, thanks @leader22 for the PR (#13)
• Added CryptoKey to the sandbox, thanks @mosch for the PR (#14)