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`

string

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

{ name: "my-worker" }

`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`

string

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

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

`modules`

boolean

default:"false"

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

{ modules: true }

`modulesRoot`

string

Root directory for resolving module imports.

{ modulesRoot: "./src" }

`modulesRules`

ModuleRule[]

Rules for importing non-JavaScript files.

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

Show ModuleRule properties

string

required

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

string[]

required

Glob patterns to match

boolean

Allow subsequent rules to match

Runtime Options

`compatibilityDate`

string

Compatibility date in YYYY-MM-DD format.

{ compatibilityDate: "2024-01-01" }

`compatibilityFlags`

string[]

Compatibility flags to enable.

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

`routes`

string[]

Route patterns this worker handles.

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

`upstream`

string

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

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

Server Options

`host`

string

default:"127.0.0.1"

Host to bind the HTTP server to.

{ host: "0.0.0.0" }

`port`

number

default:"0"

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

{ port: 8787 }

`inspectorPort`

number

Port for the Chrome DevTools inspector.

{ inspectorPort: 9229 }

Logging Options

`log`

Log

Custom logger instance.

import { Log } from "miniflare";

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

{ log: new CustomLog() }

`verbose`

boolean

Enable verbose logging.

{ verbose: true }

Binding Options

`bindings`

Record<string, any>

Simple environment variables and bindings.

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

`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`

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

string

required

Exported class name

string

Worker name that exports this class (for external DOs)

string

Custom unique key for ID generation

boolean

Prevent eviction from memory

`r2Buckets`

Record<string, string>

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

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

`d1Databases`

Record<string, string>

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

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

`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

string

required

Worker name to bind to

string

Named entrypoint to use

`queueProducers`

Record<string, string | QueueProducerOptions>

Queue producer bindings.

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

`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

number

default:"10"

Maximum messages per batch (max: 100)

number

default:"5"

Maximum seconds to wait before dispatching

number

default:"3"

Number of retries on failure

string

Queue name for failed messages

`analyticsEngineDatasets`

Record<string, string>

Analytics Engine dataset bindings.

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

Persistence Options

`defaultPersistRoot`

string

Default root directory for all persisted data.

{ defaultPersistRoot: "./.mf" }

`kvPersist`

boolean | string

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

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

`durableObjectsPersist`

boolean | string

Enable Durable Objects persistence.

{ durableObjectsPersist: true }

`r2Persist`

boolean | string

Enable R2 persistence.

{ r2Persist: true }

`d1Persist`

boolean | string

Enable D1 persistence.

{ d1Persist: true }

`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`

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`

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`

boolean

Inject live reload script into HTML responses.

{ liveReload: true }

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

​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

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