⬆️ Migrating from Version 1

Miniflare 2 includes breaking changes. This guide walks you through how to upgrade your app.

​CLI & API Changes

​Upgrade Node.js

Node.js 16.13.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/Open external link or https://github.com/nvm-sh/nvmOpen external link.

​Delete persisted Durable Object and cached data

The storage format for Durable Objects and cached responses has changed in Miniflare 2. If you were persisting to the file-system or Redis, you'll need to delete these directories/namespaces.

​Delete references to Durable Object IDs

The format for Durable Object IDs has changed in Miniflare 2 to include a hash of the object name. If you have any these stored in persisted KV data or constants, you'll need to delete them.

​Replace --disable-updater with --no-update-check

The --disable-updater flag has been renamed to --no-update-check.

​Replace --disable-cache with --no-cache

The --disable-cache flag has been renamed to --no-cache. The disableCache API option has also been replaced with cache. Replace...

const mf = new Miniflare({ disableCache: true }); // ❌

...with...

const mf = new Miniflare({ cache: false }); // ✅

​Replace miniflare.wasm_bindings with wasm_modules

The miniflare.wasm_bindings key was non-standard. It has been replaced with the standard wasm_modules key. Replace...

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

...with...

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

​Update the script_name option

The Durable Object script_name option was implemented incorrectly in Miniflare 1. It should've been the name of a worker, not a path to a script. Replace...

wrangler.toml
[durable_objects]
bindings = [
  { name = "TEST", class_name = "Test", script_name = "./api/index.mjs" }, # ❌
]

const mf = new Miniflare({
  durableObjects: {
    TEST: { className: "Test", scriptPath: "./api/index.mjs" }, // ❌
  },
});

...with...

wrangler.toml
[durable_objects]
bindings = [
  { name = "TEST", class_name = "Test", script_name = "api" }, # ✅
]
[miniflare.mounts]
api = "./api"

const mf = new Miniflare({
  durableObjects: {
    TEST: { className: "Test", scriptName: "api" }, // ✅
  },
  mounts: { api: "./api" },
});

See 📌 Durable Objects for more details.

​Install the optional @miniflare/storage-redis package

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

$ npm install @miniflare/storage-redis -D

​API Only Changes

​Automatically load configuration files

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,
});

​Replace ConsoleLog with Log

The ConsoleLog class has been replaced with the Log class. You can construct this with a LogLevel to control how much information is logged to the console. Replace...

import { Miniflare, ConsoleLog } from "miniflare";
const mf = new Miniflare({
  log: new ConsoleLog(true), // ❌
});

...with...

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

​Replace storage() with getDurableObjectStorage()

The DurableObjectStub#storage() method was non-standard, and was accessible inside workers, which was not good. It has been replaced with the Miniflare#getDurableObjectStorage() method. Replace...

const mf = new Miniflare({ ... });
const ns = await mf.getDurableObjectNamespace("TEST");
const id = ns.newUniqueId();
const stub = ns.get(id);
const storage = await stub.storage(); // ❌

...with...

const mf = new Miniflare({ ... });
const ns = await mf.getDurableObjectNamespace("TEST");
const id = ns.newUniqueId();
const storage = await mf.getDurableObjectStorage(id); // ✅

​Replace getCache() with getCaches()

The Miniflare#getCache() method has been replaced with Miniflare#getCaches(). Replace...

const mf = new Miniflare({ ... });
const defaultCache = await mf.getCache(); // ❌
const namedCache = await mf.getCache("named"); // ❌

...with...

const mf = new Miniflare({ ... });
const caches = await mf.getCaches();
const defaultCache = caches.default; // ✅
const namedCache = await caches.open("named"); // ✅

​Replace buildWatchPath with buildWatchPaths

Miniflare 2 supports watching multiple paths for changes to rebuild on. Replace...

const mf = new Miniflare({
  buildWatchPath: "./src", // ❌
});

...with...

const mf = new Miniflare({
  buildWatchPaths: ["./src"], // ✅
});

​Replace reloadOptions() with reload()

The Miniflare#reloadOptions() method has been replaced with Miniflare#reload(). Replace...

const mf = new Miniflare({ ... });
await mf.reloadOptions(); // ❌

...with...

const mf = new Miniflare({ ... });
await mf.reload(); // ✅

Miniflare 2 also adds a new Miniflare#setOptions() method which accepts the same options object as the new Miniflare constructor, applies those options, then reloads the worker.

const mf = new Miniflare({
  buildCommand: "npm run build",
  kvNamespaces: ["TEST"],
});
await mf.setOptions({
  kvNamespaces: ["TEST2"], // ✅
});

​Await createServer()

The Miniflare#createServer() method now always returns a Promise. Replace...

const mf = new Miniflare({ ... });
const server = mf.createServer(); // ❌
server.listen(5000, () => { ... });

...with...

const mf = new Miniflare({ ... });
const server = await mf.createServer(); // ✅
server.listen(5000, () => { ... });

Miniflare 2 also adds a new Miniflare#startServer() which automatically starts a server using the configured host and port.

const mf = new Miniflare({ port: 5000 });
await mf.startServer(); // ✅