Skip to content
Cloudflare Docs
Miniflare
Cloudflare Docs
Miniflare
Search icon (depiction of a magnifying glass)
GitHub icon
Visit Miniflare on GitHub
Set theme to dark (⇧+D)

🚧 Changelog

2.6.0

Features

Fixes

2.5.1

⚠️ Security Update

2.5.0

Features

Fixes

2.4.0

Features

Fixes

2.3.0

Features

Fixes

2.2.0

Features

Fixes

2.1.0

Features

  • Allow multiple build watch paths to be set in wrangler.toml files. Use the [miniflare] build_watch_dirs option. Note this gets merged with the regular [build] watch_dir option:

    [build]
    watch_dir = "src1"
    

    [miniflare]
    build_watch_dirs = ["src2", "src3"]

  • WebSocket handshake headers are now included in responses from the HTTP server and WebSocket upgrade fetches. Closes issue #151, thanks @jed.

Fixes

2.0.0

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 separately for testing.
  2. ✨ Lightweight: Miniflare 1 included 122 third-party packages with a total install size of 88MB. Miniflare 2 reduces this to 24 packages and 6MB by leveraging features included with Node.js 16.
  3. ✅ Accurate: 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.

Check out the migration guide if you're upgrading from version 1.

Notable Changes

  • ✳️ Node.js 16.7.0 is now the minimum required version
  • 🤹 Added a custom Jest test environment, allowing you to run unit tests in the Miniflare sandbox, with isolated storage for each test
  • 🔌 Added support for running multiple workers in the same Miniflare instance
  • ⚡️ Added a live reload feature (--live-reload) that automatically refreshes your browser when your worker reloads
  • 🚪 Added Durable Object input and output gates, and write coalescing
  • 🛑 Added the DurableObjectState#blockConcurrencyWhile(callback) method
  • 📅 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
  • 🗺 Automatically fetch the incoming Request#cf object from a trusted Cloudflare endpoint
  • 🎲 Added support for crypto.randomUUID()
  • 🔐 Added support for the NODE-ED25519 algorithm
  • ✉️ 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.

  • Correctly implement the Durable Object script_name option. In Miniflare 1, this incorrectly expected a script path instead of a script name. This now relies on mounting the other worker. See 📌 Durable Objects for more details.

  • 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. See 📌 Durable Objects for more details.

  • 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 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 LogLevel to control how much information is logged to the console:

    import { Miniflare, Log, LogLevel } from "miniflare";
    

    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"

  • Renamed the buildWatchPath option to buildWatchPaths. This is now an array of string paths to watch as opposed to a single string.

  • 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.

  • Replaced the Miniflare#getCache() method the Miniflare#getCaches() method. This returns the global caches object. See ✨ Cache .

  • 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.

  • 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.

  • The result of Miniflare#dispatchScheduled will no longer include undefined if a module scheduled handler doesn't return a value

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

Core:

  • Added support for running multiple workers in the same Miniflare instance. See 🔌 Multiple Workers for more details.

  • 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. See 📅 Compatibility Dates for more details.

  • Added a proper CommonJS module loader. Workers built with Webpack will be more likely to work with Miniflare now. Closes issue #44, thanks @TimTinkers.

  • Don't crash on unhandled promise rejections when using the CLI. Instead, log them. Closes issue #115, thanks @togglydev.

  • Limit the number of subrequests to 50, as per the Workers runtime. Closes issue #117, thanks @leader22 for the suggestion.

  • To match the behaviour of the Workers runtime, some functionality, such as asynchronous I/O (fetch, Cache API, KV), timeouts (setTimeout, setInterval), and generating cryptographically-secure random values (crypto.getRandomValues, crypto.subtle.generateKey), can now only be performed while handling a request.

    This behaviour can be disabled by setting the --global-async-io/globalAsyncIO, --global-timers/globalTimers and --global-random/globalRandom options respectively, which may be useful for tests or libraries that need async I/O for setup during local development. Note the Miniflare Jest environment automatically enables these options.

    KV namespaces and caches returned from Miniflare#getKVNamespace() and getCaches() are unaffected by this change, so they can still be used in tests without setting any additional options.

  • To match the behaviour of the Workers runtime, Miniflare now enforces recursion depth limits. Durable Object fetches can recurse up to 16 times, and service bindings can recurse up to 32 times. This means if a Durable Object fetch triggers another Durable Object fetch, and so on 16 times, an error will be thrown.

  • Incoming request headers are now immutable. Closes issue #36, thanks @grahamlyons.

  • Disabled dynamic WebAssembly compilation in the Miniflare sandbox

  • Fixed instanceof on primitives such as Object, Array, Promise, etc. from outside the Miniflare sandbox. This makes it much easier to run Rust workers in Miniflare, as wasm-bindgen frequently generates this code.

  • Added a new --verbose/verbose: true option that enables verbose logging with more debugging information

  • Throw a more helpful error with suggested fixes when Miniflare can't find your worker's script

  • Only rebuild parts of the sandbox that need to change when options are updated

  • Added a new reload event to Miniflare instances that is dispatched whenever the worker reloads:

    const mf = new Miniflare({ ... });
    mf.addEventListener("reload", (event) => {
      console.log("Worker reloaded!");
    });

  • Added a new Miniflare#getGlobalScope() method for getting the global scope of the Miniflare sandbox. This allows you to access and manipulate the Miniflare environment whilst your worker is running without reloading it. Closes issue #38, thanks @cdloh.

  • Added a new Miniflare#startScheduler() method that starts a CRON scheduler that dispatches scheduled events according to CRON expressions in options

  • Miniflare-added CF-* headers are now included in the HTML error response

  • Updated build script to use ES module exports of dependencies where possible. Thanks @lukeed for the PR.

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.

  • Adds highly experimental support for service bindings. This is primarily meant for internal testing, and users outside the beta can't deploy workers using this feature yet, but feel free to play around with them locally and let us know what you think in the Cloudflare Workers Discord server.

    To enable these, mount your service (so Miniflare knows where to find it) then add the binding. Note the bound service name must match the mounted name:

    $ miniflare --mount auth=./auth --service AUTH_SERVICE=auth # or -S
    # wrangler.toml
    experimental_services = [
      # Note environment is currently ignored
      { name = "AUTH_SERVICE", service = "auth", environment = "production" }
    ]
    

    [miniflare.mounts]
    auth = "./auth"
    const mf = new Miniflare({
      mounts: { auth: "./auth" },
      serviceBindings: { AUTH_SERVICE: "auth" },
    });

    ...then to use the service binding:

    export default {
      async fetch(request, env, ctx) {
        const res = await env.AUTH_SERVICE.fetch("...");
        // ...
      },
    };

    If ./auth/wrangler.toml contains its own service bindings, those services must also be mounted in the root worker (i.e. in wrangler.toml not ./auth/wrangler.toml). Nested mounts are not supported.

Builds:

Standards:

Durable Objects:

  • Added input and output gates for ensuring consistency without explicit transactions
  • Added write coalescing for put/delete without interleaving awaits for automatic atomic writes
  • Added the DurableObjectState#blockConcurrencyWhile(callback) method. This prevents new fetch events being delivered to your object whilst the callback runs. Closes issue #45, thanks @gmencz.
  • Added the DurableObjectId#equals(id) method for comparing if 2 Durable Object IDs have the same hex-ID
  • Automatically resolve relative URLs passed to DurableObjectStub#fetch(input, init?) against https://fast-host. Closes issue #27, thanks @halzy.
  • Throw an error if the string passed to DurableObjectNamespace#idFromString(hexId) is not 64 hex digits
  • Throw an error if the hex-ID passed to DurableObjectNamespace#idFromString(hexId) is for a different Durable Object
  • Throw an error if the ID passed to DurableObjectNamespace#get(id) is for a different Durable Object
  • Throw an error when keys are greater than 2KiB or undefined
  • Throw an error when values are greater than 128KiB
  • Throw an error when attempting to get, put or delete more than 128 keys, or when attempting to modify more than 128 keys in a transaction
  • Throw an error when attempting to put an undefined value
  • Throw an error when attempting to list keys with a negative limit
  • Throw an error when attempting to perform an operation in a rolledback transaction or in a transaction that has already committed
  • Throw an error when attempting to call deleteAll() in a transaction
  • Throw an error when a Durable Object fetch handler doesn't return a Response
  • Use the same V8 serialization as Cloudflare Workers to store values
  • Fixed an issue where keys added in a transaction callback were not reported as deleted in the same transaction
  • Fixed an issue where keys added in a transaction callback were not included in the list of keys in the same transaction

HTMLRewriter:

  • Remove Content-Length header from HTMLRewriter transformed Responses
  • Don't start transforming until transformed Response body is needed
  • Throw an error when attempting to transform body streams containing non-ArrayBuffer/ArrayBufferView chunks

HTTP Server:

Jest Environment:

  • Added a custom Jest test environment, allowing you to run unit tests in the Miniflare sandbox, with isolated storage for each test. See 🤹 Jest Environment for more details.

KV:

  • Throw an error when keys are empty, ., .., undefined, or greater than 512B when UTF-8 encoded
  • Throw an error when values are greater than 25MiB
  • Throw an error when metadata is greater than 1KiB
  • Throw an error when the cacheTtl option is less than 60s
  • Throw an error when expirationTtl is non-numeric, less than or equal 0, or less than 60s
  • Throw an error when expiration is non-numeric, less than or equal the current time, or less than 60s in the future
  • Throw an error when the limit passed to KVNamespace#list() is non-numeric, less than or equal 0, or greater than 1000

Scheduler:

Workers Sites:

  • Added support for the new __STATIC_CONTENT_MANIFEST text module allowing you to use Workers Sites in modules mode

Web Sockets:

1.4.1

Fixes

1.4.0

Features

Fixes

1.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

1.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

1.3.1

Fixes

1.3.0

Features

Fixes

1.2.0

Features

Fixes

  • Fixed Windows support, closes issue #10
  • Fixed issue where scripts were not reloaded correctly when editing script path in wrangler.toml. Scripts are now always reloaded on options change. Miniflare.reloadScript() is now deprecated. You should use Miniflare.reloadOptions() instead.

1.1.0

Features

  • Added support for namespaced caches with caches.open. See ✨ Cache for more details.

1.0.1

Fixes

  • Fixed /usr/bin/env: 'node --experimental-vm-modules': No such file or directory error when running the CLI in Linux. See 💻 Using the CLI for more details.

1.0.0

Breaking Changes

  • The first and only argument to the Miniflare constructor is now an object. Scripts should be specified via the script option for strings and the scriptPath option for files:

    // Previous version
    import vm from "vm";
    import { Miniflare } from "miniflare";
    

    const mf1 = new Miniflare(
      new vm.Script(`addEventListener("fetch", (event) => { ... })`),
      { kvPersist: true }
    );
    const mf2 = new Miniflare("script.js", { kvPersist: true });
    // New version
    import { Miniflare } from "miniflare";
    

    const mf1 = new Miniflare({
      script: `addEventListener("fetch", (event) => { ... })`,
      kvPersist: true,
    });
    const mf2 = new Miniflare({
      scriptPath: "script.js",
      kvPersist: true,
    });

  • The Miniflare.getNamespace method has been renamed to Miniflare.getKVNamespace

  • Logged errors will now throw a MiniflareError if no log is provided

  • When using file system KV persistence, key names are now sanitised to replace special characters such as :, /, and \. Reading keys containing these characters may now return null if a value was stored in the previous version.

Features

Fixes

  • Fixed error if options object (containing type and cacheTtl properties) passed as second parameter to KV get method, closes issue #3
  • Fixed error if ArrayBuffer passed as data to crypto.subtle.digest("md5", data)
  • Fixed handling of ignoreMethod option for Cache match and delete
  • Disabled edge caching when using Workers Sites, files are now always loaded from disk
  • Provided Set and WeakSet from Miniflare's realm to sandbox, removing Promise, so (async () => {})() instanceof Promise evaluates to true

0.1.1

Fixes

0.1.0

Initial Release

Features