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.
nameUnique identifier for the worker. Required when using multiple workers. scriptWorker script contents as a string. Mutually exclusive with scriptPath. { script : ` export default { async fetch(request) { return new Response("Hello"); } } ` , modules : true }
scriptPathPath to the worker script file. Mutually exclusive with script. { scriptPath : "./dist/worker.js" }
modulesWhether the worker uses ES modules format (vs. service worker format). modulesRootRoot directory for resolving module imports. modulesRulesRules for importing non-JavaScript files. { modulesRules : [ { type: "Text" , include: [ "**/*.txt" ] }, { type: "Data" , include: [ "**/*.bin" ] }, { type: "CompiledWasm" , include: [ "**/*.wasm" ] }, ] }
Show ModuleRule properties
Module type: "ESModule", "CommonJS", "Text", "Data", or "CompiledWasm"
Allow subsequent rules to match
Runtime Options compatibilityDateCompatibility date in YYYY-MM-DD format. { compatibilityDate : "2024-01-01" }
compatibilityFlagsCompatibility flags to enable. { compatibilityFlags : [ "nodejs_compat" , "streams_enable_constructors" ] }
routesRoute patterns this worker handles. { routes : [ "example.com/*" , "api.example.com/v1/*" ] }
upstreamUpstream URL for fetch requests that don’t match routes. { upstream : "https://example.com" }
Server Options hosthost
string
default: "127.0.0.1"
Host to bind the HTTP server to. portPort for the HTTP server. Use 0 for a random available port. inspectorPortPort for the Chrome DevTools inspector. Logging Options logCustom logger instance. import { Log } from "miniflare" ; class CustomLog extends Log { log ( message : string ) { console . log ( `[WORKER] ${ message } ` ); } } { log : new CustomLog () }
verboseBinding Options bindingsSimple environment variables and bindings. { bindings : { API_KEY : "secret" , DEBUG : true , MAX_RETRIES : 3 , } }
kvNamespacesKV namespace bindings. Map of binding names to namespace IDs. { kvNamespaces : { MY_KV : "kv-namespace-id" , CACHE : "cache-namespace-id" , } }
durableObjectsdurableObjects
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
Worker name that exports this class (for external DOs)
Custom unique key for ID generation
Prevent eviction from memory
r2BucketsR2 bucket bindings. Map of binding names to bucket names. { r2Buckets : { MY_BUCKET : "my-r2-bucket" , ASSETS : "static-assets" , } }
d1DatabasesD1 database bindings. Map of binding names to database IDs. { d1Databases : { DB : "database-id" , ANALYTICS : "analytics-db-id" , } }
serviceBindingsserviceBindings
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" , }, } }
queueProducersqueueProducers
Record<string, string | QueueProducerOptions>
Queue producer bindings. { queueProducers : { MY_QUEUE : "my-queue-name" , TASKS : { queueName : "background-tasks" }, } }
queueConsumersqueueConsumers
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
Maximum messages per batch (max: 100)
Maximum seconds to wait before dispatching
Number of retries on failure
Queue name for failed messages
analyticsEngineDatasetsAnalytics Engine dataset bindings. { analyticsEngineDatasets : { ANALYTICS : "dataset-name" , } }
Persistence Options defaultPersistRootDefault root directory for all persisted data. { defaultPersistRoot : "./.mf" }
kvPersistEnable KV persistence. true uses default path, or specify directory. { kvPersist : true } // or { kvPersist : "./.data/kv" }
durableObjectsPersistEnable Durable Objects persistence. { durableObjectsPersist : true }
r2Persistd1PersistcachePersistEnable Cache API persistence. 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 , });
workersArray of worker configurations. Each worker has all the options listed above plus a required name.
Advanced Options Custom request.cf object properties. { cf : { colo : "SJC" , country : "US" , city : "San Francisco" , } }
unsafeEvalBindingBinding name for unsafe eval functionality (for REPL-like use cases). Only use this for development tools. Never in production.
{ unsafeEvalBinding : "UNSAFE_EVAL" }
liveReloadInject live reload script into HTML responses. mountsmounts
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 } ` );