Skip to content

These docs are for Miniflare 2 which is no longer supported apart from critical security updates.
Please see the migration guide to upgrade to Miniflare 3, and the updated API docs.

Miniflare
Visit Miniflare on GitHub
Set theme to dark (⇧+D)

⬆️ 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/ or https://github.com/nvm-sh/nvm.

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(); // ✅