💻 Using the CLI

The CLI is the easiest way to get started with Miniflare. It lets you start a local HTTP server that serves requests using your worker.

Installation

Miniflare is installed using npm:

$ npm install -g miniflare # either globally...
$ npm install -D miniflare # ...or as a dev dependency

You can also install and invoke the CLI using npx:

$ npx miniflare

Usage

If worker.js contains the following worker script:

addEventListener("fetch", (event) => {
  event.respondWith(new Response("Hello Miniflare!"));
});

...running the following command will start a local HTTP server listening on port 8787 that responds with Hello Miniflare! to all requests:

 




$ miniflare worker.js
[mf:inf] Worker reloaded! (97B)
[mf:inf] Listening on :8787
[mf:inf] - http://127.0.0.1:8787

Note that the uncompressed size of the worker, 97B, is logged. Cloudflare requires all workers are under 1MiB once compressed. Miniflare will warn you when your uncompressed size exceeds 1MiB.

TIP

If you're building your worker beforehand (with esbuild, Webpack, etc), make sure you pass the path of your built output to Miniflare, not your input source code. See 🛠 Builds for more details.

If your script is defined in a wrangler.toml or package.json file, or you're using Wrangler's "webpack" or "rust" worker types, you don't need to pass a script as a command line argument: Miniflare will infer it automatically.

Watching and Debugging

Add --watch/-w and --debug/-d flags to reload the worker whenever worker.js changes and log debug information (including processed options) respectively:

 








$ miniflare worker.js --watch --debug
[mf:dbg] Options:
[mf:dbg] - Scripts: worker.js
[mf:dbg] Reloading worker.js...
[mf:inf] Worker reloaded! (97B)
[mf:dbg] Watching .env, package.json, worker.js, wrangler.toml...
[mf:inf] Listening on :8787
[mf:inf] - http://127.0.0.1:8787

Configuration Autoloading

Note that .env, package.json and wrangler.toml files are also being watched. These files are always loaded automatically and configure your worker's environment in addition to the CLI flags. See the Wrangler Configuration reference below for more details, but as an example, with the following wrangler.toml file and worker.js files:

[vars]
KEY = "value"
addEventListener("fetch", (event) => {
  event.respondWith(new Response(KEY));
});

...the local HTTP server would respond with value to all requests. The Guide goes into more detail on configuring specific features. To load a different wrangler.toml file, use the --wrangler-config/-c flag:

$ miniflare worker.js --wrangler-config wrangler.other.toml

Script Requirement

The only required option is the script to run. This can either be passed as a command line argument as we've been doing so far, in a wrangler.toml file or in a package.json file. The command line argument takes priority, then the script in wrangler.toml, then the main or module field in package.json (depending on whether modules support is enabled):

# wrangler.toml
[build.upload]
dir = "" # Defaults to "dist"
main = "./worker.js"
// package.json
{
  "main": "worker.js", // "service-worker" format
  "module": "worker.mjs" // "modules" format
}

HTTPS Server

By default, Miniflare starts an HTTP server. To start an HTTPS server instead, set the https option. To use an automatically generated self-signed certificate, use the --https flag. This certificate is cached and will be valid for 30 days. The certificate will be renewed if it expires in less than 2 days:

$ miniflare worker.js --https # Cache certificate in ./.mf/cert
$ miniflare worker.js --https ./cert_cache # Cache in ./cert_cache instead

To use an existing certificate instead, use the --https-key, --https-cert, --https-ca and --https-pfx to set the paths to it. If these are encrypted, use the --https-passphrase flag to set the passphrase:

$ miniflare worker.js --https-key ./key.pem --https-cert ./cert.pem

Update Checker

The CLI includes an automatic update checker that looks for new versions of Miniflare once a day. As Cloudflare are always improving and tweaking workers, you should aim to install these promptly for improved compatibility with the real workers environment. You can disable this with the --disable-updater flag.

Reference

Flags

Usage: miniflare [script] [options]

Options:
  -h, --help              Show help                                    [boolean]
  -v, --version           Show version number                          [boolean]
  -H, --host              HTTP server host to listen on (all by default)[string]
  -p, --port              HTTP server port (8787 by default)            [number]
  -d, --debug             Log debug messages                           [boolean]
  -c, --wrangler-config   Path to wrangler.toml                         [string]
      --wrangler-env      Environment in wrangler.toml to use           [string]
      --package           Path to package.json                          [string]
  -m, --modules           Enable modules                               [boolean]
      --modules-rule      Modules import rule (TYPE=GLOB)                [array]
      --build-command     Command to build project                      [string]
      --build-base-path   Working directory for build command           [string]
      --build-watch-path  Directory to watch for rebuilding on changes  [string]
  -w, --watch             Watch files for changes                      [boolean]
  -u, --upstream          URL of upstream origin                        [string]
  -t, --cron              Cron pattern to trigger scheduled events with  [array]
  -k, --kv                KV namespace to bind                           [array]
      --kv-persist        Path to persist KV data to (omit path for default)
      --cache-persist     Path to persist cached data to (omit path for default)
      --disable-cache     Disable caching with default/named caches    [boolean]
  -s, --site              Path to serve Workers Site files from         [string]
      --site-include      Glob pattern of site files to serve            [array]
      --site-exclude      Glob pattern of site files not to serve        [array]
  -o, --do                Durable Object to bind (NAME=CLASS)            [array]
      --do-persist        Path to persist Durable Object data to (omit path for
                          default)
  -e, --env               Path to .env file                             [string]
  -b, --binding           Bind variable/secret (KEY=VALUE)               [array]
      --wasm              WASM module to bind (NAME=PATH)                [array]
      --https             Enable self-signed HTTPS
      --https-key         Path to PEM SSL key                           [string]
      --https-cert        Path to PEM SSL cert chain                    [string]
      --https-ca          Path to SSL trusted CA certs                  [string]
      --https-pfx         Path to PFX/PKCS12 SSL key/cert chain         [string]
      --https-passphrase  Passphrase to decrypt SSL files               [string]
      --disable-updater   Disable update checker                       [boolean]

Wrangler Configuration

Miniflare uses the default Wrangler configuration keys for most of its features. For Miniflare specific options, the keys are in the special [miniflare] section.

kv_namespaces = [                  ## --kv
  { binding = "TEST_NAMESPACE", id = "", preview_id = "" }
]

[durable_objects]
bindings = [                       ## --do
  { name = "OBJECT", class_name = "Object", script_name = "./object.mjs" }
]

[vars]                             ## --binding
KEY = "value"

[site]
bucket = "./public"                ## --site
include = ["upload_dir"]           ## --site-include
exclude = ["ignore_dir"]           ## --site-exclude

[triggers]
crons = ["30 * * * *"]             ## --cron

[build]
command = "npm run build"          ## --build-command
cwd = "build_cwd"                  ## --build-base-path
watch_dir = "build_watch_dir"      ## --build-watch-path
[build.upload]
format = "modules"                 ## --modules
dir = "worker"
main = "./index.mjs"               ## [script]
[[build.upload.rules]]             ## --modules-rule
type = "ESModule"
globs = ["**/*.js"]

[miniflare]
upstream = "https://miniflare.dev" ## --upstream
kv_persist = true                  ## --kv-persist
cache_persist = "./cache"          ## --cache-persist
disable_cache = true               ## --disable-cache
durable_objects_persist = true     ## --do-persist
env_path = ".env.test"             ## --env
host = "127.0.0.1"                 ## --host
port = 1337                        ## --port
wasm_bindings = [                  ## --wasm
  { name = "MODULE", path="module.wasm" }
]
disable_updater = true             ## --disable-updater
https = true                       ## --https
https = "./cert_cache"             ## --https ./cert_cache
[miniflare.https]
key = "./key.pem"                  ## --https-key
cert = "./cert.pem"                ## --https-cert
ca = "./ca.pem"                    ## --https-ca
pfx = "./pfx.pfx"                  ## --https-pfx
passphrase = "pfx passphrase"      ## --https-passphrase