Miniflare Options Reference - Cloudflare Workers SDK

Miniflare accepts a comprehensive set of options for configuring Workers, bindings, and runtime behavior.

Worker Options

These options configure the Worker script and module system.

`name`

name

string

Unique identifier for the worker. Required when using multiple workers.

{ name: "my-worker" }

`script`

script

string

Worker script contents as a string. Mutually exclusive with scriptPath.

{
  script: `
    export default {
      async fetch(request) {
        return new Response("Hello");
      }
    }
  `,
  modules: true
}

`scriptPath`

scriptPath

string

Path to the worker script file. Mutually exclusive with script.

{ scriptPath: "./dist/worker.js" }

`modules`

modules

boolean

default:"false"

Whether the worker uses ES modules format (vs. service worker format).

{ modules: true }

`modulesRoot`

modulesRoot

string

Root directory for resolving module imports.

{ modulesRoot: "./src" }

`modulesRules`

modulesRules

ModuleRule[]

Rules for importing non-JavaScript files.

{
  modulesRules: [
    { type: "Text", include: ["**/*.txt"] },
    { type: "Data", include: ["**/*.bin"] },
    { type: "CompiledWasm", include: ["**/*.wasm"] },
  ]
}

Show ModuleRule properties

type

string

required

Module type: "ESModule", "CommonJS", "Text", "Data", or "CompiledWasm"

include

string[]

required

Glob patterns to match

fallthrough

boolean

Allow subsequent rules to match

Runtime Options

`compatibilityDate`

compatibilityDate

string

Compatibility date in YYYY-MM-DD format.

{ compatibilityDate: "2024-01-01" }

`compatibilityFlags`

compatibilityFlags

string[]

Compatibility flags to enable.

{
  compatibilityFlags: [
    "nodejs_compat",
    "streams_enable_constructors"
  ]
}

`routes`

routes

string[]

Route patterns this worker handles.

{
  routes: [
    "example.com/*",
    "api.example.com/v1/*"
  ]
}

`upstream`

upstream

string

Upstream URL for fetch requests that don’t match routes.

{ upstream: "https://example.com" }

Server Options

`host`

host

string

default:"127.0.0.1"

Host to bind the HTTP server to.

{ host: "0.0.0.0" }

`port`

port

number

default:"0"

Port for the HTTP server. Use 0 for a random available port.

{ port: 8787 }

`inspectorPort`

inspectorPort

number

Port for the Chrome DevTools inspector.

{ inspectorPort: 9229 }

Logging Options

`log`

log

Log

Custom logger instance.

import { Log } from "miniflare";

class CustomLog extends Log {
  log(message: string) {
    console.log(`[WORKER] ${message}`);
  }
}

{ log: new CustomLog() }

`verbose`

verbose

boolean

Enable verbose logging.

{ verbose: true }

Binding Options

`bindings`

bindings

Record<string, any>

Simple environment variables and bindings.

{
  bindings: {
    API_KEY: "secret",
    DEBUG: true,
    MAX_RETRIES: 3,
  }
}

`kvNamespaces`

kvNamespaces

Record<string, string>

KV namespace bindings. Map of binding names to namespace IDs.

{
  kvNamespaces: {
    MY_KV: "kv-namespace-id",
    CACHE: "cache-namespace-id",
  }
}

`durableObjects`

durableObjects

Record<string, string | DurableObjectOptions>

Durable Object bindings.

{
  durableObjects: {
    // Simple: binding name -> class name
    COUNTER: "Counter",
    // Advanced: with options
    ROOM: {
      className: "ChatRoom",
      scriptName: "chat-worker", // from another worker
    },
  }
}

Show DurableObjectOptions

className

string

required

Exported class name

scriptName

string

Worker name that exports this class (for external DOs)

unsafeUniqueKey

string

Custom unique key for ID generation

unsafePreventEviction

boolean

Prevent eviction from memory

`r2Buckets`

r2Buckets

Record<string, string>

R2 bucket bindings. Map of binding names to bucket names.

{
  r2Buckets: {
    MY_BUCKET: "my-r2-bucket",
    ASSETS: "static-assets",
  }
}

`d1Databases`

d1Databases

Record<string, string>

D1 database bindings. Map of binding names to database IDs.

{
  d1Databases: {
    DB: "database-id",
    ANALYTICS: "analytics-db-id",
  }
}

`serviceBindings`

serviceBindings

Record<string, string | ServiceDesignator>

Service bindings to other workers.

{
  serviceBindings: {
    // Simple: binding name -> worker name
    AUTH: "auth-worker",
    // With entrypoint
    API: {
      name: "api-worker",
      entrypoint: "PublicAPI",
    },
  }
}

Show ServiceDesignator

name

string

required

Worker name to bind to

entrypoint

string

Named entrypoint to use

`queueProducers`

queueProducers

Record<string, string | QueueProducerOptions>

Queue producer bindings.

{
  queueProducers: {
    MY_QUEUE: "my-queue-name",
    TASKS: { queueName: "background-tasks" },
  }
}

`queueConsumers`

queueConsumers

Record<string, QueueConsumerOptions>

Queue consumer configuration. Map of queue names to options.

{
  queueConsumers: {
    "my-queue": {
      maxBatchSize: 10,
      maxBatchTimeout: 5,
      maxRetries: 3,
      deadLetterQueue: "failed-queue",
    },
  }
}

Show QueueConsumerOptions

maxBatchSize

number

default:"10"

Maximum messages per batch (max: 100)

maxBatchTimeout

number

default:"5"

Maximum seconds to wait before dispatching

maxRetries

number

default:"3"

Number of retries on failure

deadLetterQueue

string

Queue name for failed messages

`analyticsEngineDatasets`

analyticsEngineDatasets

Record<string, string>

Analytics Engine dataset bindings.

{
  analyticsEngineDatasets: {
    ANALYTICS: "dataset-name",
  }
}

Persistence Options

`defaultPersistRoot`

defaultPersistRoot

string

Default root directory for all persisted data.

{ defaultPersistRoot: "./.mf" }

`kvPersist`

kvPersist

boolean | string

Enable KV persistence. true uses default path, or specify directory.

{ kvPersist: true }
// or
{ kvPersist: "./.data/kv" }

`durableObjectsPersist`

durableObjectsPersist

boolean | string

Enable Durable Objects persistence.

{ durableObjectsPersist: true }

`r2Persist`

r2Persist

boolean | string

Enable R2 persistence.

{ r2Persist: true }

`d1Persist`

d1Persist

boolean | string

Enable D1 persistence.

{ d1Persist: true }

`cachePersist`

cachePersist

boolean | string

Enable Cache API persistence.

{ cachePersist: true }

Multi-Worker Options

For running multiple workers in the same Miniflare instance:

const mf = new Miniflare({
  workers: [
    {
      name: "api",
      scriptPath: "./api.js",
      modules: true,
      routes: ["api.example.com/*"],
      serviceBindings: {
        AUTH: "auth",
      },
    },
    {
      name: "auth",
      scriptPath: "./auth.js",
      modules: true,
      d1Databases: {
        DB: "users-db",
      },
    },
  ],
  // Shared options
  defaultPersistRoot: "./.mf",
  d1Persist: true,
});

`workers`

workers

WorkerOptions[]

Array of worker configurations. Each worker has all the options listed above plus a required name.

Advanced Options

`cf`

object

Custom request.cf object properties.

{
  cf: {
    colo: "SJC",
    country: "US",
    city: "San Francisco",
  }
}

`unsafeEvalBinding`

unsafeEvalBinding

string

Binding name for unsafe eval functionality (for REPL-like use cases).

Only use this for development tools. Never in production.

{ unsafeEvalBinding: "UNSAFE_EVAL" }

`liveReload`

liveReload

boolean

Inject live reload script into HTML responses.

{ liveReload: true }

`mounts`

mounts

Record<string, MiniflareOptions>

Mount other Miniflare instances at specific routes.

{
  mounts: {
    "/api": {
      scriptPath: "./api-worker.js",
      modules: true,
    },
  }
}

Complete Example

import { Miniflare } from "miniflare";

const mf = new Miniflare({
  // Worker configuration
  name: "my-app",
  scriptPath: "./dist/worker.js",
  modules: true,
  modulesRules: [
    { type: "Text", include: ["**/*.txt"] },
    { type: "CompiledWasm", include: ["**/*.wasm"] },
  ],

  // Runtime
  compatibilityDate: "2024-01-01",
  compatibilityFlags: ["nodejs_compat"],
  
  // Server
  host: "127.0.0.1",
  port: 8787,
  
  // Bindings
  bindings: {
    ENVIRONMENT: "development",
    API_KEY: process.env.API_KEY,
  },
  kvNamespaces: {
    CACHE: "cache-kv",
  },
  d1Databases: {
    DB: "main-db",
  },
  r2Buckets: {
    UPLOADS: "user-uploads",
  },
  durableObjects: {
    ROOM: "ChatRoom",
  },
  
  // Persistence
  defaultPersistRoot: "./.mf",
  kvPersist: true,
  d1Persist: true,
  r2Persist: true,
  durableObjectsPersist: true,
  
  // Logging
  verbose: true,
});

await mf.ready;
const url = await mf.getServiceURL();
console.log(`Worker running at ${url}`);

Wrangler API

Miniflare API

Testing

Integrations

Documentation Index

​Worker Options

​name

​script

​scriptPath

​modules

​modulesRoot

​modulesRules

​Runtime Options

​compatibilityDate

​compatibilityFlags

​routes

​upstream

​Server Options

​host

​port

​inspectorPort

​Logging Options

​log

​verbose

​Binding Options

​bindings

​kvNamespaces

​durableObjects

​r2Buckets

​d1Databases

​serviceBindings

​queueProducers

​queueConsumers

​analyticsEngineDatasets

​Persistence Options

​defaultPersistRoot

​kvPersist

​durableObjectsPersist

​r2Persist

​d1Persist

​cachePersist

​Multi-Worker Options

​workers

​Advanced Options

​cf

​unsafeEvalBinding

​liveReload

​mounts

​Complete Example

Build docs developers (and LLMs) love

Worker Options

`name`

`script`

`scriptPath`

`modules`

`modulesRoot`

`modulesRules`

Runtime Options

`compatibilityDate`

`compatibilityFlags`

`routes`

`upstream`

Server Options

`host`

`port`

`inspectorPort`

Logging Options

`log`

`verbose`

Binding Options

`bindings`

`kvNamespaces`

`durableObjects`

`r2Buckets`

`d1Databases`

`serviceBindings`

`queueProducers`

`queueConsumers`

`analyticsEngineDatasets`

Persistence Options

`defaultPersistRoot`

`kvPersist`

`durableObjectsPersist`

`r2Persist`

`d1Persist`

`cachePersist`

Multi-Worker Options

`workers`

Advanced Options

`cf`

`unsafeEvalBinding`

`liveReload`

`mounts`

Complete Example