🔥 Miniflare

Miniflare 3 is a simulator for developing and testing Cloudflare Workers, powered by workerd.

:warning: Miniflare 3 is API-only, and does not expose a CLI. Use Wrangler with wrangler dev --experimental-local to develop your Workers locally with Miniflare 3.

Quick Start

$ npm install @miniflare/tre --save-dev

import { Miniflare } from "@miniflare/tre";

// Create a new Miniflare instance, starting a workerd server
const mf = new Miniflare({
  script: `addEventListener("fetch", (event) => {
    event.respondWith(new Response("Hello Miniflare!"));
  })`,
});

// Send a request to the workerd server, the host is ignored
const response = await mf.dispatchFetch("http://localhost:8787/");
console.log(await response.text()); // Hello Miniflare!

// Cleanup Miniflare, shutting down the workerd server
await mf.dispose();

API

:warning: Features marked (Experimental) may change at any point and are not subject to semantic versioning guarantees.

type Awaitable<T>

T | Promise<T>

Represents a value that can be awaited. Used in callback types to allow Promises to be returned if necessary.

type Json

string | number | boolean | null | Record<string, Json> | Json[]

Represents a JSON-serialisable value.

type ModuleRuleType

"ESModule" | "CommonJS" | "Text" | "Data" | "CompiledWasm"

Represents how a module's contents should be interpreted.

• "ESModule": interpret as ECMAScript module
• "CommonJS": interpret as CommonJS module
• "Text": interpret as UTF8-encoded data, expose in runtime with string-typed default export
• "Data": interpret as arbitrary binary data, expose in runtime with ArrayBuffer-typed default export
• "CompiledWasm": interpret as binary WebAssembly module data, expose in runtime with WebAssembly.Module-typed default export

interface ModuleDefinition

Represents a manually defined module.

• type: ModuleRuleType

  How this module's contents should be interpreted.

• path: string

  Path of this module. The module's "name" will be obtained by converting this to a relative path. The original path will be used to read contents if it's omitted.

• contents?: string | Uint8Array

  Contents override for this module. Binary data should be passed as Uint8Arrays. If omitted, will be read from path.

interface ModuleRule

Represents a rule for identifying the ModuleRuleType of automatically located modules.

• type: ModuleRuleType

  How to interpret modules that match the include patterns.

• include: string[]

  Glob patterns to match located module paths against (e.g. ["**/*.txt"]).

• fallthrough?: boolean

  If true, ignore any further rules of this type. This is useful for disabling the built-in ESModule and CommonJS rules that match *.mjs and *.js/*.cjs files respectively.

type Persistence

boolean | string | undefined

Represents where data should be persisted, if anywhere.

• If this is undefined or false, data will be stored in-memory and only persist between Miniflare#setOptions() calls, not restarts nor new Miniflare instances.
• If this is true, data will be stored on the file-system, in the $PWD/.mf directory.
• If this looks like a URL, then:
  • If the protocol is memory:, data will be stored in-memory as above.
  • If the protocol is file:, data will be stored on the file-system, in the specified directory (e.g. file:///path/to/directory). If the unsanitise search parameter is true, path sanitisation will be disabled.
  • If the protocol is sqlite:, data will be stored in an SQLite database, at the specified path (e.g. sqlite:///path/to/db.sqlite).
  • (Experimental) If the protocol is remote:, data will be read/written from/to real data stores on the Cloudflare network. By default, this will cache data in-memory, but the cache search parameter can be set to a URL-encoded persistence string to customise this. Note, this feature is only supported for KV namespaces at the moment, and requires the cloudflareFetch option to be set.
• Otherwise, if this is just a regular string, data will be stored on the file-system, using the value as the directory path.

enum LogLevel

NONE, ERROR, WARN, INFO, DEBUG, VERBOSE

Controls which messages Miniflare logs. All messages at or below the selected level will be logged.

interface LogOptions

• prefix?: string

  String to add before the level prefix when logging messages. Defaults to mf.

• suffix?: string

  String to add after the level prefix when logging messages.

class Log

• constructor(level?: LogLevel, opts?: LogOptions)

  Creates a new logger that logs all messages at or below the specified level to the console.

• error(message: Error)

  Logs a message at the ERROR level. If the constructed log level is less than ERROR, throws the message instead.

• warn(message: string)

  Logs a message at the WARN level.

• info(message: string)

  Logs a message at the INFO level.

• debug(message: string)

  Logs a message at the DEBUG level.

• verbose(message: string)

  Logs a message at the VERBOSE level.

class NoOpLog extends Log

• constructor()

  Creates a new logger that logs nothing to the console, and always throws messages logged at the ERROR level.

interface WorkerOptions

Options for an individual Worker/"nanoservice". All bindings are accessible on the global scope in service-worker format Workers, or via the 2nd env parameter in module format Workers.

Core

• name?: string

  Unique name for this worker. Only required if multiple workers are specified.

• script?: string

  JavaScript code for this worker. If this is a service worker format Worker, it must not have any imports. If this is a modules format Worker, it must not have any npm imports, and modules: true must be set. If it does have imports, scriptPath must also be set so Miniflare knows where to resolve them relative to.

• scriptPath?: string

  Path of JavaScript entrypoint. If this is a service worker format Worker, it must not have any imports. If this is a modules format Worker, it must not have any npm imports, and modules: true must be set.

• modules?: boolean | ModuleDefinition[]

  • If true, Miniflare will treat script/scriptPath as an ES Module and automatically locate transitive module dependencies according to modulesRules. Note that automatic location is not perfect: if the specifier to a dynamic import() or require() is not a string literal, an exception will be thrown.

  • If set to an array, modules can be defined manually. Transitive dependencies must also be defined. Note the first module must be the entrypoint and have type "ESModule".

• modulesRoot?: string

  If modules is set to an array, modules' "name"s will be their paths relative to this value. This ensures file paths in stack traces are correct.

• modulesRules?: ModuleRule[]

  Rules for identifying the ModuleRuleType of automatically located modules when modules: true is set. Note the following default rules are always included at the end:

  [
    { type: "ESModule", include: ["**/*.mjs"] },
    { type: "CommonJS", include: ["**/*.js", "**/*.cjs"] },
  ]

  If script and scriptPath are set, and modules is set to an array, modules takes priority for a Worker's code, followed by script, then scriptPath.

• compatibilityDate?: string

  Compatibility date to use for this Worker. Defaults to a date far in the past.

• compatibilityFlags?: string[]

  Compatibility flags to use for this Worker.

• bindings?: Record<string, Json>

  Record mapping binding name to arbitrary JSON-serialisable values to inject as bindings into this Worker.

• wasmBindings?: Record<string, string>

  Record mapping binding name to paths containing binary WebAssembly module data to inject as WebAssembly.Module bindings into this Worker.

• textBlobBindings?: Record<string, string>

  Record mapping binding name to paths containing UTF8-encoded data to inject as string bindings into this Worker.

• dataBlobBindings?: Record<string, string>

  Record mapping binding name to paths containing arbitrary binary data to inject as ArrayBuffer bindings into this Worker.

• serviceBindings?: Record<string, string | { network: Network } | { external: ExternalServer } | { disk: DiskDirectory } | (request: Request) => Awaitable<Response>>

  Record mapping binding name to service designators to inject as { fetch: typeof fetch } service bindings into this Worker.

  • If the designator is a string, requests will be dispatched to the Worker with that name.
  • If the designator is an object of the form { network: { ... } }, where network is a workerd Network struct, requests will be dispatched according to the fetched URL.
  • If the designator is an object of the form { external: { ... } } where external is a workerd ExternalServer struct, requests will be dispatched to the specified remote server.
  • If the designator is an object of the form { disk: { ... } } where disk is a workerd DiskDirectory struct, requests will be dispatched to an HTTP service backed by an on-disk directory.
  • If the designator is a function, requests will be dispatched to your custom handler. This allows you to access data and functions defined in Node.js from your Worker.

Cache

• cache?: boolean

  If false, default and named caches will be disabled. The Cache API will still be available, it just won't cache anything.

• cacheWarnUsage?: boolean

  If true, the first use of the Cache API will log a warning stating that the Cache API is unsupported on workers.dev subdomains.

Durable Objects

• durableObjects?: Record<string, string | { className: string, scriptName?: string }>

  Record mapping binding name to Durable Object class designators to inject as DurableObjectNamespace bindings into this Worker.

  • If the designator is a string, it should be the name of a class exported by this Worker.
  • If the designator is an object, and scriptName is undefined, className should be the name of a class exported by this Worker.
  • Otherwise, className should be the name of a class exported by the Worker with a name of scriptName.

KV

• kvNamespaces?: Record<string, string> | string[]

  Record mapping binding name to KV namespace IDs to inject as KVNamespace bindings into this Worker. Different Workers may bind to the same namespace ID with different binding names. If a string[] of binding names is specified, the binding name and KV namespace ID are assumed to be the same.

• sitePath?: string

  Path to serve Workers Sites files from. If set, __STATIC_CONTENT and __STATIC_CONTENT_MANIFEST bindings will be injected into this Worker. In modules mode, __STATIC_CONTENT_MANIFEST will also be exposed as a module with a string-typed default export, containing the JSON-stringified manifest. Note Workers Sites files are never cached in Miniflare.

• siteInclude?: string[]

  If set, only files with paths matching these glob patterns will be served.

• siteExclude?: string[]

  If set, only files with paths not matching these glob patterns will be served.

R2

• r2Buckets?: Record<string, string> | string[]

  Record mapping binding name to R2 bucket names to inject as R2Bucket bindings into this Worker. Different Workers may bind to the same bucket name with different binding names. If a string[] of binding names is specified, the binding name and bucket name are assumed to be the same.

D1

• d1Databases?: Record<string, string> | string[]

  Record mapping binding name to D1 database IDs to inject as Fetcher bindings into this Worker. Note these bindings must be wrapped with a facade to provide the expected D1Database API. Different Workers may bind to the same database ID with different binding names. If a string[] of binding names is specified, the binding name and database ID are assumed to be the same.

Analytics Engine and Queues

Not yet supported

interface SharedOptions

Options shared between all Workers/"nanoservices".

Core

• host?: string

  Hostname that the workerd server should listen on. Defaults to 127.0.0.1.

• port?: number

  Port that the workerd server should listen on. Tries to default to 8787, but falls back to a random free port if this is in use. Note if a manually specified port is in use, Miniflare throws an error, rather than attempting to find a free port.

• inspectorPort?: number

  Port that workerd should start a DevTools inspector server on. Visit chrome://inspect in a Chromium-based browser to connect to this. This can be used to see detailed console.logs, profile CPU usage, and will eventually allow step-through debugging.

• verbose?: boolean

  Enable workerd's --verbose flag for verbose logging. This can be used to see simplified console.logs.

• log?: Log

  Logger implementation for Miniflare's errors, warnings and informative messages.

• cf?: boolean | string | Record<string, any>

  Controls the object returned from incoming Request's cf property.

  • If set to a falsy value, an object with default placeholder values will be used
  • If set to an object, that object will be used
  • If set to true, a real cf object will be fetched from a trusted Cloudflare endpoint and cached in node_modules/.mf for 30 days
  • If set to a string, a real cf object will be fetched and cached at the provided path for 30 days

• liveReload?: boolean

  If true, Miniflare will inject a script into HTML responses that automatically reloads the page in-browser whenever the Miniflare instance's options are updated.

• (Experimental) cloudflareFetch?: (resource: string, searchParams?: URLSearchParams, init?: RequestInit) => Awaitable<Response>

  Authenticated fetch used by remote: storage to communicate with the Cloudflare API. https://api.cloudflare.com/client/v4/accounts/<account_id>/ should be prepended to resource to form the request URL. Appropriate authorization headers should also be added.

Cache, Durable Objects, KV, R2 and D1

• cachePersist?: Persistence

  Where to persist data cached in default or named caches. See docs for Persistence.

• durableObjectsPersist?: Persistence

  Not yet supported, Miniflare will throw if this is truthy and Durable Object bindings are specified.

• kvPersist?: Persistence

  Where to persist data stored in KV namespaces. See docs for Persistence.

• r2Persist?: Persistence

  Where to persist data stored in R2 buckets. See docs for Persistence.

• d1Persist?: Persistence

  Where to persist data stored in D1 databases. See docs for Persistence.

Analytics Engine and Queues

Not yet supported

type MiniflareOptions

SharedOptions & (WorkerOptions | { workers: WorkerOptions[] })

Miniflare accepts either a single Worker configuration or multiple Worker configurations in the workers array. When specifying an array of Workers, the first Worker is designated the entrypoint and will receive all incoming HTTP requests. Some options are shared between all workers and should always be defined at the top-level.

class Miniflare

• constructor(opts: MiniflareOptions)

  Creates a Miniflare instance and starts a new workerd server. Note unlike Miniflare 2, Miniflare 3 always starts a HTTP server listening on the configured host and port: there are no createServer/startServer functions.

• setOptions(opts: MiniflareOptions)

  Updates the configuration for this Miniflare instance and restarts the workerd server. Note unlike Miniflare 2, this does not merge the new configuration with the old configuration.

• ready: Promise<URL>

  Returns a Promise that resolves with a http URL to the workerd server once it has started and is able to accept requests.

• dispatchFetch(input: RequestInfo, init?: RequestInit): Promise<Response>

  Sends a HTTP request to the workerd server, dispatching a fetch event in the entrypoint Worker. Returns a Promise that resolves with the response. Note that this implicitly waits for the ready Promise to resolve, there's no need to do that yourself first. Additionally, the host of the request's URL is always ignored and replaced with the workerd server's.

• dispose(): Promise<void>

  Cleans up the Miniflare instance, and shuts down the workerd server. Note that after this is called, setOptions and dispatchFetch cannot be called.