🕸 Web Standards

• Web Standards ReferenceOpen external link
• Encoding ReferenceOpen external link
• Fetch ReferenceOpen external link
• Request ReferenceOpen external link
• Response ReferenceOpen external link
• Streams ReferenceOpen external link
• Using StreamsOpen external link
• Web Crypto ReferenceOpen external link

Miniflare supports the following Web Standards in its sandbox:

• Console: console.*
• Timers: setTimeout, setInterval, clearTimeout, clearInterval, queueMicrotask, AbortSignal.timeout, scheduler.wait
• Base64: atob, btoa
• Web Crypto: crypto.getRandomValues, crypto.randomUUID, crypto.subtle.* (with support for MD5 digests and NODE-ED25519 signatures), crypto.DigestStream
• Encoding: TextEncoder, TextDecoder
• Fetch: fetch, Headers (including non-standard getAll methodOpen external link), Request, Response, FormData, Blob, File, URL, URLPattern, URLSearchParams (powered by undiciOpen external link)
• Streams: ByteLengthQueuingStrategy, CountQueuingStrategy, ReadableByteStreamController, ReadableStream, ReadableStreamBYOBReader (including non-standard readAtLeast method), ReadableStreamBYOBRequest, ReadableStreamDefaultController, ReadableStreamDefaultReader, TransformStream, TransformStreamDefaultController, WritableStream, WritableStreamDefaultController, WritableStreamDefaultWriter, IdentityTransformStream, FixedLengthStream, CompressionStream, DecompressionStream
• Events: Event, EventTarget, AbortController, AbortSignal
• Event Types: fetch, scheduled, unhandledrejection, rejectionhandled
• Misc: structuredClone, navigator

​Mocking Outbound fetch Requests

When using the API, Miniflare allows you to substitute custom Responses for fetch() calls using undici's MockAgent APIOpen external link. This is useful for testing workers that make HTTP requests to other services. To enable fetch mocking, create a MockAgentOpen external link using the createFetchMock() function, then set this using the fetchMock option. If you're using the 🤹 Jest Environment, use the global getMiniflareFetchMock() function to obtain a correctly set-up MockAgentOpen external link.

import { Miniflare } from "miniflare";
import { createFetchMock } from "@miniflare/core";

// Create `MockAgent` and connect it to the `Miniflare` instance
const fetchMock = createFetchMock();
const mf = new Miniflare({
  script: `export default {
    async fetch(request, env, ctx) {
      const res = await fetch("https://example.com/thing");
      const text = await res.text();
      return new Response(\`response:\${text}\`);
    }
  }`,
  modules: true,
  fetchMock,
});

// Throw when no matching mocked request is found
// (see https://undici.nodejs.org/#/docs/api/MockAgent?id=mockagentdisablenetconnect)
fetchMock.disableNetConnect();

// Mock request to https://example.com/thing
// (see https://undici.nodejs.org/#/docs/api/MockAgent?id=mockagentgetorigin)
const origin = fetchMock.get("https://example.com");
// (see https://undici.nodejs.org/#/docs/api/MockPool?id=mockpoolinterceptoptions)
origin
  .intercept({ method: "GET", path: "/thing" })
  .reply(200, "Mocked response!");

const res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.text()); // "response:Mocked response!"

​Subrequests

To match the behaviour of the Workers runtime, Miniflare limits you to 50 subrequests per requestOpen external link. Each call to fetch(), each URL in a redirect chain, and each call to a Cache API method (put()/match()/delete()) counts as a subrequest.

If needed, the subrequest limit to be customised using the MINIFLARE_SUBREQUEST_LIMIT environment variable. Setting this to a negative number disables the limit. Setting this to 0 disables subrequests.

$ MINIFLARE_SUBREQUEST_LIMIT=100 miniflare

​Frozen Time

To match the behaviour of the Workers runtimeOpen external link, Miniflare will always return the time of last I/O from new Date() and Date.now().

This behaviour can be disabled by setting the actualTime option, which may be useful for performance testing. Note that the Miniflare 🤹 Jest Environment automatically enables this option.

Using the CLICLI
Using wrangler.tomlwrangler.toml
Using the APIJavaScript API
$ miniflare --actual-time
wrangler.toml
[miniflare]
actual_time = true
const mf = new Miniflare({
  actualTime: true,
});

​Global Functionality Limits

To match the behaviour of the Workers runtimeOpen external link, 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 only be performed while handling a request, not in the global scope.

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

Using the CLICLI
Using wrangler.tomlwrangler.toml
Using the APIJavaScript API
$ miniflare --global-async-io --global-timers --global-random
wrangler.toml
[miniflare]
global_async_io = true
global_timers = true
glboal_random = true
const mf = new Miniflare({
  globalAsyncIO: true,
  globalTimers: true,
  globalRandom: true,
});

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

​instanceof, constructor and prototype Checks

Miniflare overrides instanceof checks for primitive classes like Object so they succeed for values created both inside and outside the Miniflare sandbox (in a different JavaScript realm). This ensures dynamic type checking often performed by WebAssembly glue code (e.g. wasm-bindgen) always succeeds. Note that values returned by Workers runtime APIs are created outside the Miniflare sandbox. See this fileOpen external link for more details.

Primitive classes in this case are defined as JavaScript built-ins that can be instantiated by something other than their constructor (e.g. literals, functions, runtime errors):

• Object
• Function
• Array
• Promise
• RegExp
• Error, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError

Primitive constructor and prototype checks cannot be trapped easily and so will fail for values created outside the Miniflare sandbox.

import { Miniflare } from "miniflare";

const mf = new Miniflare({
  bindings: {
    OBJECT: { a: 1 },
    ARRAY: new Uint8Array([1, 2, 3]),
  },
  modules: true,
  script: `
    export default {
      async fetch(request, env, ctx) {
        console.log({ a: 1 } instanceof Object); // ✅ true
        console.log(new Uint8Array([1, 2, 3]) instanceof Object); // ✅ true
        console.log({ a: 1 }.constructor === Object); // ✅ true
        console.log(Object.getPrototypeOf({ a: 1 }) === Object.prototype); // ✅ true
        
        console.log(env.OBJECT instanceof Object); // ✅ true
        console.log(env.ARRAY instanceof Object); // ✅ true
        console.log(env.OBJECT.constructor === Object); // ❌ false
        console.log(Object.getPrototypeOf(env.OBJECT) === Object.prototype); // ❌ false
        
        throw new Error("oops!");
      }
    }
  `,
});

try {
  await mf.dispatchFetch("http://localhost");
} catch (e) {
  console.log(e instanceof Error); // ❌ false
}

By default, primitive instanceof checks outside the Miniflare sandbox will fail for values created inside the sandbox (e.g. checking types of thrown exceptions in tests). To fix this, pass the primitive class in from Node.js as a custom global. Note this will cause primitive instanceof checks to fail for values created without the constructor inside the sandbox.

const mf = new Miniflare({
  globals: { Error },
  modules: true,
  script: `
    export default {
      async fetch(request, env, ctx) {
        throw new Error("oops!");
      }
    }
  `,
});

try {
  await mf.dispatchFetch("http://localhost");
} catch (e) {
  console.log(e instanceof Error); // ✅ true
}