⬆️ Migrating from Version 2

kvNamespaces/r2Buckets/d1Databases

• In addition to string[]s, these options now accept Record<string, string>s, mapping binding names to namespace IDs/bucket names/database IDs. This means multiple Workers can bind to the same namespace/bucket/database under different names.

queueBindings

• Renamed to queueProducers. This either accepts a Record<string, string> mapping binding names to queue names, or a string[] of binding names to queues of the same name.

queueConsumers

• Either accepts a Record<string, QueueConsumerOptions> mapping queue names to consumer options, or a string[] of queue names to consume with default options. QueueConsumerOptions has the following type:

  interface QueueConsumerOptions {
    // https://developers.cloudflare.com/queues/platform/configuration/#consumer
    maxBatchSize?: number;                  // default: 5
    maxBatchTimeout?: number /* seconds */; // default: 1
    maxRetries?: number;                    // default: 2
    deadLetterQueue?: string;               // default: none
  }

cfFetch

• Renamed to cf. Either accepts a boolean, string (as before), or an object to use a the cf object for incoming requests.

wranglerConfigPath/wranglerConfigEnv

• Miniflare no longer handles Wrangler's configuration. To programmatically start up a Worker based on Wrangler configuration, use the unstable_dev()Open external link API.

packagePath

• Miniflare no longer loads script paths from package.json files. Use the scriptPath option to specify your script instead.

watch

• Miniflare's API is primarily intended for testing use cases, where file watching isn't usually required. This option was here to enable Miniflare’s CLI which has now been removed. If you need to watch files, consider using a separate file watcher like fs.watch()Open external link or chokidarOpen external link, and calling setOptions() with your original configuration on change.

logUnhandledRejections

• Unhandled rejections can be handled in Workers with addEventListener("unhandledrejection")Open external link.

globals

• Injecting arbitrary globals is not supported by workerdOpen external link. If you're using a service worker, bindings will be injected as globals, but these must be JSON-serialisable.

https/httpsKey(Path)/httpsCert(Path)/httpsPfx(Path)/httpsPassphrase

• Miniflare does not support starting HTTPS servers yet. These options may be added back in a future release.

crons

• workerdOpen external link does not support triggering scheduled events yet. This option may be added back in a future release.

mounts

• Miniflare no longer has the concept of parent and child Workers. Instead, all Workers can be defined at the same level, using the new workers option. Here's an example that uses a service binding to increment a value in a shared KV namespace:

  import { Miniflare, Response } from "miniflare";
  
  const message = "The count is ";
  const mf = new Miniflare({
    // Options shared between workers such as HTTP and persistence configuration
    // should always be defined at the top level.
    host: "0.0.0.0",
    port: 8787,
    kvPersist: true,
  
    workers: [
      {
        name: "worker",
        kvNamespaces: { COUNTS: "counts" },
        serviceBindings: {
          INCREMENTER: "incrementer",
          // Service bindings can also be defined as custom functions, with access
          // to anything defined outside Miniflare.
          async CUSTOM(request) {
            // `request` is the incoming `Request` object.
            return new Response(message);
          },
        },
        modules: true,
        script: `export default {
          async fetch(request, env, ctx) {
            // Get the message defined outside
            const response = await env.CUSTOM.fetch("http://host/");
            const message = await response.text();
  
            // Increment the count 3 times
            await env.INCREMENTER.fetch("http://host/");
            await env.INCREMENTER.fetch("http://host/");
            await env.INCREMENTER.fetch("http://host/");
            const count = await env.COUNTS.get("count");
  
            return new Response(message + count);
          }
        }`,
      },
      {
        name: "incrementer",
        // Note we're using the same `COUNTS` namespace as before, but binding it
        // to `NUMBERS` instead.
        kvNamespaces: { NUMBERS: "counts" },
        // Worker formats can be mixed-and-matched
        script: `addEventListener("fetch", (event) => {
          event.respondWith(handleRequest());
        })
        async function handleRequest() {
          const count = parseInt((await NUMBERS.get("count")) ?? "0") + 1;
          await NUMBERS.put("count", count.toString());
          return new Response(count.toString());
        }`,
      },
    ],
  });
  const res = await mf.dispatchFetch("http://localhost");
  console.log(await res.text()); // "The count is 3"
  await mf.dispose();

metaProvider

• The cf object and X-Forwarded-Proto/X-Real-IP headers can be specified when calling dispatchFetch() instead. A default cf object can be specified using the new cf option too.

durableObjectAlarms

• Miniflare now always enables Durable Object alarms.

globalAsyncIO/globalTimers/globalRandom

• workerdOpen external link cannot support these options without fundamental changes.

actualTime

• Miniflare now always returns the current time.

inaccurateCpu

• Set the inspectorPort: 9229 option to enable the V8 inspector. Visit chrome://inspect in Google Chrome to open DevTools and perform CPU profiling.

• Miniflare v3 now requires a full configuration object to be passed, instead of a partial patch.

• Call setOptions() with the original configuration object to reload Miniflare.

• Miniflare now always starts a workerdOpen external link server listening on the configured host and port, so these methods are redundant.

• The functionality of dispatchScheduled can now be done via getWorker(). For more information read the scheduled events documentation.

• Use the queue() method on service bindingsOpen external link or queue producer bindingsOpen external link instead.

• These methods returned objects from inside the Workers sandbox. Since Miniflare now uses workerdOpen external link, which runs in a different process, these methods can no longer be supported.

• Miniflare no longer emits reload events. As Miniflare no longer watches files, reloads are only triggered by initialisation or setOptions() calls. In these cases, it's possible to wait for the reload with either await mf.ready or await mf.setOptions() respectively.

• workerdOpen external link does not support waiting for all waitUntil()ed promises yet.

• Miniflare is now contained within a single miniflare package.