- Add support for dead-letter queues. Thanks @jbw1991 for the PR.
- Add
getMiniflareDurableObjectIds()
global function to Miniflare's Jest/Vitest environments for listing active Durable Objects. CallinggetMiniflareDurableObjectIds("TEST_OBJECT")
will return aPromise
that resolves to an array of activeDurableObjectId
s for theTEST_OBJECT
namespace. Closes issue #384, thanks @DaniFoldi for the PR.
- Strip quotes from R2
onlyIf
header values. Closes issue #402, thanks @vincentbernat and @CraigglesO for the PR. - Disable
r2Persist
option in Miniflare's Jest/Vitest environments. Thanks @hanford for the PR.
- Add support for
TextEncoderStream
/TextDecoderStream
. Closes issue #389, thanks @vlovich.
- Fix reporting of server port when using
--port=0
. Closes issue #381, thanks @GregBrimble for the PR. - Return Durable Object
get()
s in lexicographic order. Closes issue #393, thanks @vlovich. - Add missing
@miniflare/r2
dependency to@miniflare/shared-test-environment
package. Thanks @askoufis for the PR. - Return correct
Content-Length
fromCache#match()
partial responses. Closes issue #406. Thanks @notorca for the PR. - Fix links in Vitest test environment docs. Thanks @eadmundo for the PR.
-
πΎ Add support for D1. Closes issue #277, thanks @geelen for the PR. Docs coming soonβ’... π
-
πͺ Add
getMiniflareDurableObjectState()
andrunWithMiniflareDurableObjectGates()
functions to the Jest/Vitest environments. This allows you to construct and call instance methods of Durable Objects directly, without having to fetch through a stub. Closes issue #157, thanks @jorroll.// Durable Object class, would probably come from an import class Counter { constructor(state) { this.storage = state.storage; } async fetch() { const count = ((await this.storage.get("count")) ?? 0) + 1; void this.storage.put("count", count); return new Response(String(count)); } } const env = getMiniflareBindings(); // Use standard Durable Object bindings to generate IDs const id = env.COUNTER.newUniqueId(); // Get DurableObjectState, and seed data const state = await getMiniflareDurableObjectState(id); await state.storage.put("count", 3); // Construct object directly const object = new Counter(state, env); // Call instance method directly, closing input gate, // and waiting for output gate to open const res = await runWithMiniflareDurableObjectGates(state, () => object.fetch(new Request("http://localhost/")) ); expect(await res.text()).toBe("4");
-
π₯· Don't construct corresponding Durable Object instance when calling
Miniflare#getDurableObjectStorage()
. This allows you to seed data before your Durable Object's constructor is invoked. Closes issue #300, thanks @spigaz. -
βοΈ Add support for
WebSocket#readyState
andWebSocket.READY_STATE_{CONNECTING,OPEN,CLOSING,CLOSED}
constants. Note these constant names intentionally deviate from the spec to match the Workers runtime. -
π Add persistent history to the REPL. This respects the
MINIFLARE_REPL_HISTORY
,MINIFLARE_REPL_HISTORY_SIZE
, andMINIFLARE_REPL_MODE
environment variables based on Node's. -
π΅ Add support for
Range
,If-Modified-Since
andIf-None-Match
headers onRequest
s toCache#match
. Closes issue #246.
- Don't wait for
waitUntil
Promise
s to resolve before opening WebSocket connections - Allow WebSockets to be
close()
d on receiving aclose
event. Closes issue #331, thanks @awthwathje. - Ensure calling
WebSocket#close()
before returning a WebSocket response sends the correct close code and reason. - Fix delivery of incoming
WebSocket
error
events - Ensure only scheduled Durable Object alarms are flushed. Previously, flushing
all alarms would attempt to execute the
alarm
handler of every constructed Durable Object instance, even if that instance hadn't scheduled an alarm, or didn't have analarm
handler. - Delay scheduled missed alarms. Previously, if Durable Object persistence was enabled, and an alarm should've executed when Miniflare wasn't running, Miniflare may have crashed on startup. Closes issue #359, thanks @AlCalzone.
- Allow empty-chunk writes to
IdentityTransformStream
. Closes issue #374, thanks @cdloh. - Don't hang when fetching from Durable Objects with fake-timers installed. Closes issue #190, thanks @vlovich.
- Match unimplemented
Request
/Response
properties with the Workers runtime. Specifically, throw unimplemented errors when attempting to accessRequest#{context,mode,credentials,integrity,cache}
andResponse#{type,useFinalUrl}
. - Discard
Content-Length: NaN
headers as a temporary workaround until cloudflare/kv-asset-handler#295 is released. Closes honojs/hono#520, thanks @Cherry. - Return byte streams when
tee()
ing byte streams to match the behaviour of the Workers runtime. Closes issues #317 and #375. - Throw
TypeError
when callingFetcher#fetch
with an illegal this to match the behaviour of the Workers runtime.
- Allow WebSocket client connection errors to be caught. Closes issue #229, thanks @viorel-d.
- Return
Response
s with immutable headers fromcache.match
s. Closes issue #365, thanks @AlCalzone. - Ensure
request.cf.clientAcceptEncoding
is always astring
. Closes issue #362, thanks @GregBrimble.
- Add missing
@miniflare/queues
dependencies. Closes issue #360, thanks @AlCalzone for the PR. - Fix support for queues in Jest/Vitest testing environments
- β‘οΈ Add custom Vitest testing environment. This behaves almost identically
to the Jest environment. However, isolated storage must be installed manually
in each test file. Call the
setupMiniflareIsolatedStorage()
global function and use the returneddescribe
function instead of the regulardescribe
/suite
functions imported fromvitest
. See β‘οΈ Vitest Environment for more details. - π Populate Workers Sites
__STATIC_CONTENT_MANIFEST
with site files instead of an empty object. Miniflare will still disable caching of Workers Sites files to ensure the most up-to-date files are always returned. Closes issues #233, #326 and cloudflare/wrangler2#1632. Thanks @ItalyPaleAle, @Skye-31, @CraigglesO, @Hexstream and @PolariTOON. - β± Add global
getMiniflareWaitUntil()
method andExecutionContext
class to the Jest and Vitest testing environments. This can be used toawait
the results ofwaitUntil
edPromise
s in tests. See π€ΉοΈ Jest Environment and β‘οΈ Vitest Environment for more details. Closes issue #202, thanks @jamesarosen and @CraigglesO for the PR. - β³ Match Web Streams implementations with Workers runtime, closes issue
#168, thanks
@leviwolfe:
- Add support for the non-standard
IdentityTransformStream
class. - Add support for the
streams_enable_constructors
compatibility flag.ReadableStream
andWritableStream
constructors will throw unless this flag is enabled.ReadableByteStreamController
,ReadableStreamBYOBRequest
,ReadableStreamDefaultController
andWritableStreamDefaultController
will only be included in the sandbox if this flag is enabled. - Add support for the
transformstream_enable_standard_constructor
compatibility flag.TransformStream
will behave likeIdentityTransformStream
if this isn't enabled, ignoring custom transformers. Iftransformstream_enable_standard_constructor
is set, butstreams_enable_constructors
isn't, theTransformStream
constructor will throw.TransformStreamDefaultController
will only be included in the sandbox if both flags are enabled. - Add support for BYOB reads to the non-standard
FixedLengthStream
class.
- Add support for the non-standard
- π¬π§ Add support for Queues. Docs coming soonβ’... π
- π Allow calls to
addEventListener
,removeEventListener
anddispatchEvent
in modules mode. Please note, callingaddEventListener
with a special event type (e.g.fetch
,scheduled
) will log a warning prompting you to use theexport default
syntax. Closes issue #207, thanks @Electroid. - π Add experimental and highly-inaccurate request CPU time measurements. These
are not representative of deployed worker performance, should only be used for
relative comparisons, and may be removed in the future. Enable measurements
with the
--inaccurate-cpu
/[miniflare] inaccurate_cpu
/inaccurateCpu
option. Closes issue #161. Thanks @alexandernst and @y21. - π¦ Automatically enable watch mode when
live_reload = true
is set inwrangler.toml
.
- Return
Response
s with immutable headers fromfetch
es to Durable Objects and service bindings. Closes issue #346, thanks @Cherry. - Fix
CryptoKey#algorithm.name
property ofNODE-ED25519
keys. Closes issue panva/jose#446, thanks @ItalyPaleAle. - Disable automatic insertion of
Sec-WebSocket-Protocol
header. Closes issue #179, thanks @aboodman and @grgbkr. - Return
Content-Length
header is customContent-Encoding
is specified. Closes issue #313, thanks @vlovich. - Require
"automatic"
instead of"auto"
for theencodeBody
option when constructingRequest
s. Closes issue #357, thanks @GregBrimble for the PR. - Remove
request.cf.cacheTtl
/request.cf.cacheTtlByStatus
support from the Cache API to match the behaviour of the Workers runtime, which only supportsrequest.cf.cacheKey
.
- Ensure initialisation is complete before tear down in
Miniflare#dispose()
. Closes issue #341, thanks @vlovich. - Ensure
DurableObjectTransaction
operations are executed in program order. Closes issue #344, thanks @vlovich.
β οΈ Miniflare's minimum supported Node.js version is now16.13.0
. This was the first LTS release of Node.js 16.We recommend you use the latest Node.js version if possible, as Cloudflare Workers use a very up-to-date version of V8. Consider using a Node.js version manager such as https://volta.sh/ or https://github.com/nvm-sh/nvm.
-
π Add support for easily mocking outbound
fetch
requests. See πΈ Web Standards for more details. Closes issue #162, thanks @william1616 for the PR.test("mocks fetch", async () => { // Get correctly set up `MockAgent` const fetchMock = getMiniflareFetchMock(); // Throw when no matching mocked request is found fetchMock.disableNetConnect(); // Mock request to https://example.com/thing const origin = fetchMock.get("https://example.com"); origin .intercept({ method: "GET", path: "/thing" }) .reply(200, "Mocked response!"); const res = await fetch("https://example.com/thing"); const text = await res.text(); expect(text).toBe("Mocked response!"); });
-
π½ Add support to immediately invoke ("flush") scheduled Durable Object alarms in the π€Ή Jest Environment. Closes issue #322, thanks @robertcepa and @CraigglesO for the PR.
test("flushes alarms", async () => { // Get Durable Object stub const env = getMiniflareBindings(); const id = env.TEST_OBJECT.newUniqueId(); const stub = env.TEST_OBJECT.get(id); // Schedule Durable Object alarm await stub.fetch("http://localhost/"); // Flush all alarms... await flushMiniflareDurableObjectAlarms(); // ...or specify an array of `DurableObjectId`s to flush await flushMiniflareDurableObjectAlarms([id]); });
-
πͺ£ Add support for R2 bucket bindings to the π€Ή Jest Environment. Closes issue #305, thanks @Cerberus for the PR.
-
2οΈβ£ Add support for Wrangler 2's
routes
property. Closes issue #254, thanks @jrencz for the PR. -
β οΈ Upgradeundici
to5.9.1
. Thanks @yusukebe and @cameron-robey for the PRs.
- Return custom
Content-Encoding
s, closes issue #312, thanks @vlovich. - Fix reading symlinked files from Miniflare's file-system storage. Closes issue #318, thanks @CraigglesO for the PR.
- Display all accessible addresses when listening on host
0.0.0.0
. Closes issue cloudflare/wrangler2#1652, thanks @Skye-31 for the PR. - Fix unbounded recursion when calling
Date.now()
/new Date()
without--actual-time
flag. Closes issue #314, thanks @WalshyDev and @AggressivelyMeows. - Preserve full path in
File#name
field. Thanks @yusefnapora for the PR. - Change underlying glob matching implementation to
picomatch
. Closes issue #244, thanks @jed and @cometkim for the PR. - Fix
NotSupportedError
when using theNODE-ED25519
algorithm in recent versions of Node.js. Closes issue #310, thanks @yusefnapora for the PR.
- πͺ£ Add support for R2 bucket bindings. Closes issue #276, thank you so much @CraigglesO for the massive PR.
- Add support for
navigator.userAgent
. Closes issue #209, thanks @Electroid. - Return fixed time from
new Date()
/Date.now()
, unless the--actual-time
/actualTime: true
option is set, to match the behaviour the Workers runtime. Closes issue #225, thanks @ItalyPaleAle. - Add support for
(De)CompressionStream
. Closes issue #206, thanks @Electroid. - Add an interactive REPL via the
--repl
flag. Any other flag can be passed too, and options will automatically be loaded fromwrangler.toml
files. Specifying a script is optional when--repl
is enabled. The REPL can also be started programmatically via theMiniflare#startREPL()
method. See for more details. Thanks @threepointone for the idea over at cloudflare/wrangler2#1263.
- Load service bindings from
services
instead ofexperimental_services
, and usebinding
instead ofname
for the binding name. Thanks @jrencz for the PR. issue #280. - Log warning instead of error when fetching
Request#cf
object fails. Closes issue #224, thanks @threepointone. - Increase the subrequest limit for
unbound
workers from 50 to 1000, and limit the number of calls to internal APIs such as KV/Durable Object to 1000. Closes issue #274, thanks @isaac-mcfadyen. - Fix logging of accessible hosts in Node.js 18
- Remove
name
fromDurableObjectId
s inDurableObjectState
to match the behaviour of the Workers runtime. Closes issue #219. - Allow failure WebSocket upgrade responses. Closes issue #174, thanks @jinjor.
- Correctly handle internationalised domain names in routes. Closes issue #186, thanks @dsod.
- Improve the error message when Durable Object bindings are missing a script to mention mounting. Closes issue #221, thanks @konsumer.
- Allow WebSockets to be closed without a status code. Closes issue #284, thanks @hansottowirtz.
- Allow Durable Object alarms to be scheduled less than 30 seconds in the future. Closes issue #290, thanks @wighawag and @CraigglesO for the PR.
- Fix
DurableObjectStorage#list()
when alarms are scheduled. Closes issue #297, thanks @evanderkoogh and @CraigglesO for the PR.
- Upgrade
undici
to5.5.1
, addressing GHSA-pgw7-wx7w-2w33 - Upgrade
node-forge
to1.3.1
, addressing GHSA-2r2c-g63r-vccr, GHSA-x4jg-mjrx-434g and GHSA-cfm4-qjh2-4765 - Upgrade
minimist
to1.2.6
, addressing GHSA-xvch-5gv4-984h
- β° Add support for Durable Object alarms. Thanks @CraigglesO for the PR.
- Add support for
URLPattern
. Closes issue #199, thanks @Electroid and @tom-sherman for the PR. - Add support for the
Response.json()
static method. Closes issue #272, thanks @Cherry. - Add support for the
startAfter
Durable Objectlist()
option. Closes issue #266, thanks @vlovich. - Add support for Jest 28 and custom
export conditions.
By default, the Miniflare Jest environment will use the
worker
condition, followed bybrowser
. Closes issues #249 and #255, thanks @awwong1 and @SupremeTechnopriest.
- Fixed issue where
403 Forbidden
responses were returned when a site behind Cloudflare was set as the upstream. Closes issue #237, thanks @james-maher for the PR. - Respect
env_path
option inwrangler.toml
when using mounts or the Miniflare Jest environment. Closes issue #240, thanks @bkniffler. - Fix cases where BYOB readers didn't notice the end of the stream. Closes issue #192, thanks @vlovich for the PR.
- Wait for unawaited writes within a Durable Object transaction before attempting to commit. Closes issue #250, thanks @vlovich.
- Correctly bind
this
incrypto
andcrypto.subtle
. Closes issue #256, thanks @lmcarreiro and @awwong1 for the PR. - Bump
busboy
to resolve a security issue. Closes issue #267, thanks @grempe and @Cherry for the PR. - Set incoming
Accept-Encoding
headers togzip
and put actual client encodings inrequest.cf.clientAcceptEncoding
to match the behaviour of the Workers runtime. Closes issue #180, thanks @evanderkoogh and @leader22 for the PR. - Remove restriction
on supported
TextDecoder
encodings. Closes issue #212. - Make
headers
on returnedfetch
Response
s immutable. Closes issue #242, thanks @nickreese. - Use lexicographic ordering for KV/Durable Object
list()
s. Closes issue #235, thanks @vlovich. - Re-export
Request
,RequestInfo
,RequestInit
andResponse
fromminiflare
. Closes issue #258, thanks @ajwootto. - Add
jest-environment-miniflare
's missingdependencies
. Thanks @BasixKOR for the PR.
- Add support for
[text_blobs]
. Closes issue #211, thanks @caass for the PR. - Add support for
[data_blobs]
. Closes issue #231, thanks @threepointone for the PR. - Do not display the pretty error page when making requests with
curl
. Closes issue #198, thanks @GregBrimble for the PR.
- Pass correctly-typed value to
webcrypto.getRandomValues()
. Closes issue #188, thanks @vlovich. - Fix
fetch
withContent-Length: 0
header. Closes issue #193, thanks @orls for the PR. - Bind
this
towebcrypto
methods, fixingcrypto.getRandomValues()
andcrypto.subtle.generateKey()
. Thanks @szkl for the PR.
- Route
/cdn-cgi/mf/scheduled
requests based on mount routes. Closes issue #163, thanks @jed. - Add clear error if a Durable Object class is missing a
fetch
handler. Closes issue #164, thanks @aboodman. - Upgrade
undici
to4.13.0
- Fix
instanceof
when subclassingError
. Subclasses ofError
were previously treated asError
s themselves ininstanceof
checks. Closes issue #159, thanks @valeriangalliat. - Return
null
bodies whenfetch
ingResponse
s with a null status. Closes issue #165, thanks @lukaszczerpak for reporting this and @GregBrimble for the PR. - Clone
ArrayBuffer
bodies when constructingRequest
/Response
s. Closes issue #171, thanks @segator and @leader22. - Watch
index.js
by default intype = "webpack"
projects - Throw
TypeError
s instead ofstring
s onHTMLRewriter
parser errors - Disable nested mounts via
Miniflare#getMount().setOptions()
- Add support for the
HTMLRewriter
Element#onEndTag(handler)
method - Add support for the
html_rewriter_treats_esi_include_as_void_tag
compatibility flag - Make the error message when attempting to import Node.js built-in modules more helpful
- Fix
instanceof
checks withnull
values. Closes issues #152 and #154. Thanks @Cerberus for the PR, and @bduff9, @huw & @g45t345rt for reporting this. - Fix subdirectory watching on Linux. Closes issue #153, thanks @huw for reporting this.
- Throw a
TypeError
instead of astring
when the parameter passed to aHTMLRewriter
handler is used outside the handler
-
Allow multiple build watch paths to be set in
wrangler.toml
files. Use the[miniflare] build_watch_dirs
option. Note this gets merged with the regular[build] watch_dir
option:[build] watch_dir = "src1" [miniflare] build_watch_dirs = ["src2", "src3"]
-
WebSocket handshake headers are now included in responses from the HTTP server and WebSocket upgrade
fetch
es. Closes issue #151, thanks @jed.
- Allow Miniflare to be installed with Yarn PnP. Closes issue #144, thanks @lookfirst, @merceyz, and @DJtheRedstoner.
- Use the actual body length for the
Content-Length
header in HTTP server responses, instead of the value provided in theResponse
constructor. Closes issue #148, thanks @lukaszczerpak. - Don't rewrite the
Host
header to match the upstream URL. Closes issue #149, thanks @hansede. - Bump dependencies, fixing
npm audit
warnings. Thanks @leader22 for the PR. - Make
instanceof
spec-compliant, ensuring checks likeObject instanceof Object
succeed. This particular check was used by Lodash's_.isPlainObject()
method, which is internally called by_.merge()
, causing unexpected results. - Make the unimplemented
Response#type
property non-enumerable - Copy header guard when
clone()
ingRequest
s, ensuringRequest
s with immutable headers still have immutable headers whenclone()
ed - Fix race conditions in file-system watcher
Miniflare 2 has been completely redesigned from version 1 with 3 primary design goals:
- π Modular: Miniflare 2 splits Workers components (KV, Durable Objects,
etc.) into separate packages (
@miniflare/kv
,@miniflare/durable-objects
, etc.) that you can import separately for testing. - β¨ Lightweight: Miniflare 1 included
122 third-party packages with a
total install size of
88MB
. Miniflare 2 reduces this to 24 packages and6MB
by leveraging features included with Node.js 16. - β Accurate: Miniflare 2 more accurately replicates the quirks and thrown errors of the real Workers runtime, so you'll know before you deploy if things are going to break.
Check out the migration guide if you're upgrading from version 1.
- β³οΈ Node.js 16.7.0 is now the minimum required version
- π€Ή Added a custom Jest test environment, allowing you to run unit tests in the Miniflare sandbox, with isolated storage for each test
- π Added support for running multiple workers in the same Miniflare instance
- β‘οΈ Added a live reload feature (
--live-reload
) that automatically refreshes your browser when your worker reloads - πͺ Added Durable Object input and output gates, and write coalescing
- π Added the
DurableObjectState#blockConcurrencyWhile(callback)
method - π
Added support for compatibility dates and flags:
durable_object_fetch_requires_full_url
,fetch_refuses_unknown_protocols
,formdata_parser_supports_files
- π Added a proper CommonJS module loader
- πΊ Automatically fetch the incoming
Request#cf
object from a trusted Cloudflare endpoint - π² Added support for
crypto.randomUUID()
- π Added support for the
NODE-ED25519
algorithm - βοΈ Added support for sending/receiving binary WebSocket messages
-
Node.js 16.7.0 is now the minimum required version. You should use the latest Node.js version if possible, as Cloudflare Workers use a very up-to-date version of V8. Consider using a Node.js version manager such as https://volta.sh/ or https://github.com/nvm-sh/nvm.
-
Changed the storage format for Durable Objects and cached responses. If you're using file-system or Redis storage, you'll need to delete these directories/namespaces.
-
Changed the Durable Object ID format to include a hash of the object name. Durable Object IDs generated in Miniflare 1 cannot be used with Miniflare 2.
-
Correctly implement the Durable Object
script_name
option. In Miniflare 1, this incorrectly expected a script path instead of a script name. This now relies on mounting the other worker. See π Durable Objects for more details. -
Removed the non-standard
DurableObjectStub#storage()
method. To access Durable Object storage outside a worker, use the newMiniflare#getDurableObjectStorage(id)
method, passing aDurableObjectId
obtained from a stub. See π Durable Objects for more details. -
Renamed the
--disable-cache
/disableCache: true
option to--no-cache
/cache: false
-
Renamed the
--disable-updater
option to--no-update-check
-
When using the API,
wrangler.toml
,package.json
and.env
are no longer automatically loaded from their default locations. To re-enable this behaviour, set these options totrue
:const mf = new Miniflare({ wranglerConfigPath: true, packagePath: true, envPath: true, });
-
Replaced the
ConsoleLog
class with theLog
class from@miniflare/shared
. You can construct this with aLogLevel
to control how much information is logged to the console:import { Miniflare, Log, LogLevel } from "miniflare"; const mf = new Miniflare({ log: new Log(LogLevel.DEBUG), });
-
Load WASM bindings from the standard
wasm_modules
wrangler.toml
key instead ofminiflare.wasm_bindings
.--- filename: wrangler.toml --- [miniflare] wasm_bindings = [ { name = "MODULE1", path="module1.wasm" }, { name = "MODULE2", path="module2.wasm" } ]
...should now be...
--- filename: wrangler.toml --- [wasm_modules] MODULE1 = "module1.wasm" MODULE2 = "module2.wasm"
-
Renamed the
buildWatchPath
option tobuildWatchPaths
. This is now an array of string paths to watch as opposed to a single string. -
Replaced the
Miniflare#reloadOptions()
method with theMiniflare#reload()
andMiniflare#setOptions({ ... })
methods.reload()
will reload options fromwrangler.toml
(useful if not watching), andsetOptions()
accepts the same options object as thenew Miniflare
constructor, applies those options, then reloads the worker. -
Replaced the
Miniflare#getCache()
method theMiniflare#getCaches()
method. This returns the globalcaches
object. See β¨ Cache . -
Miniflare#createServer()
now always returns aPromise
which you must await to get ahttp.Server
/https.Server
instance. You may want to check out the newMiniflare#startServer()
method which automatically starts a server using the configuredhost
andport
. -
Redis support is no longer included by default. If you're persisting KV, Durable Objects or cached responses in Redis, you must install the
@miniflare/storage-redis
optional peer dependency. -
Replaced how Miniflare sanitises file paths for file-system storage so namespace separators (
/
,\
,:
and|
) now create new directories. -
The result of
Miniflare#dispatchScheduled
will no longer includeundefined
if a module scheduled handler doesn't return a value
Cache:
- Added support for
cf.cacheKey
,cf.cacheTtl
andcf.cacheTtlByStatus
onRequest
. Closes issue #37, thanks @cdloh. - Added the
CF-Cache-Status: HIT
header to matchedResponse
s - Log warning when trying to use cache with
workers_dev = true
inwrangler.toml
. Cache operations are a no-op onworkers.dev
subdomains. - Throw errors when trying to cache Web Socket, non-
GET
,206 Partial Content
, orVary: *
responses - Throw an error when trying to
open
a cache with a name longer than1024
characters
CLI:
- Separated command line options into sections
- Validate types of all command line options
Core:
-
Added support for running multiple workers in the same Miniflare instance. See π Multiple Workers for more details.
-
Added support for compatibility dates and flags, specifically the flags
durable_object_fetch_requires_full_url
,fetch_refuses_unknown_protocols
,formdata_parser_supports_files
are now supported. This feature is exposed under the--compat-date
and--compat-flag
CLI options, in addition to the standard keys inwrangler.toml
. Closes issue #48, thanks @PaganMuffin. See π Compatibility Dates for more details. -
Added a proper CommonJS module loader. Workers built with Webpack will be more likely to work with Miniflare now. Closes issue #44, thanks @TimTinkers.
-
Don't crash on unhandled promise rejections when using the CLI. Instead, log them. Closes issue #115, thanks @togglydev.
-
Limit the number of subrequests to 50, as per the Workers runtime. Closes issue #117, thanks @leader22 for the suggestion.
-
To match the behaviour of the Workers runtime, some functionality, such as asynchronous I/O (
fetch
, Cache API, KV), timeouts (setTimeout
,setInterval
), and generating cryptographically-secure random values (crypto.getRandomValues
,crypto.subtle.generateKey
), can now only be performed while handling a request.This behaviour can be disabled by setting the
--global-async-io
/globalAsyncIO
,--global-timers
/globalTimers
and--global-random
/globalRandom
options respectively, which may be useful for tests or libraries that need async I/O for setup during local development. Note the Miniflare Jest environment automatically enables these options.KV namespaces and caches returned from
Miniflare#getKVNamespace()
andgetCaches()
are unaffected by this change, so they can still be used in tests without setting any additional options. -
To match the behaviour of the Workers runtime, Miniflare now enforces recursion depth limits. Durable Object
fetch
es can recurse up to 16 times, and service bindings can recurse up to 32 times. This means if a Durable Object fetch triggers another Durable Object fetch, and so on 16 times, an error will be thrown. -
Incoming request headers are now immutable. Closes issue #36, thanks @grahamlyons.
-
Disabled dynamic WebAssembly compilation in the Miniflare sandbox
-
Fixed
instanceof
on primitives such asObject
,Array
,Promise
, etc. from outside the Miniflare sandbox. This makes it much easier to run Rust workers in Miniflare, aswasm-bindgen
frequently generates this code. -
Added a new
--verbose
/verbose: true
option that enables verbose logging with more debugging information -
Throw a more helpful error with suggested fixes when Miniflare can't find your worker's script
-
Only rebuild parts of the sandbox that need to change when options are updated
-
Added a new reload event to
Miniflare
instances that is dispatched whenever the worker reloads:const mf = new Miniflare({ ... }); mf.addEventListener("reload", (event) => { console.log("Worker reloaded!"); });
-
Added a new
Miniflare#getGlobalScope()
method for getting the global scope of the Miniflare sandbox. This allows you to access and manipulate the Miniflare environment whilst your worker is running without reloading it. Closes issue #38, thanks @cdloh. -
Added a new
Miniflare#startScheduler()
method that starts a CRON scheduler that dispatchesscheduled
events according to CRON expressions in options -
Miniflare-added
CF-*
headers are now included in the HTML error response -
Updated build script to use ES module exports of dependencies where possible. Thanks @lukeed for the PR.
Bindings:
-
Added
--global KEY=VALUE
/globals: { KEY: "value" }
option for binding arbitrary values to the global scope. This behaves exactly like the--binding
/bindings: { ... }
option, but always binds to the global scope, even in modules mode. -
Added a new global variable
MINIFLARE
to the Miniflare sandbox, which will always have the valuetrue
when your script is running within Miniflare -
Miniflare now stringifies all environment variables from
wrangler.toml
. Closes issue #50, thanks @ozburo. -
Adds highly experimental support for service bindings. This is primarily meant for internal testing, and users outside the beta can't deploy workers using this feature yet, but feel free to play around with them locally and let us know what you think in the Cloudflare Workers Discord server.
To enable these, mount your service (so Miniflare knows where to find it) then add the binding. Note the bound service name must match the mounted name:
$ miniflare --mount auth=./auth --service AUTH_SERVICE=auth # or -S
# wrangler.toml experimental_services = [ # Note environment is currently ignored { name = "AUTH_SERVICE", service = "auth", environment = "production" } ] [miniflare.mounts] auth = "./auth"
const mf = new Miniflare({ mounts: { auth: "./auth" }, serviceBindings: { AUTH_SERVICE: "auth" }, });
...then to use the service binding:
export default { async fetch(request, env, ctx) { const res = await env.AUTH_SERVICE.fetch("..."); // ... }, };
If
./auth/wrangler.toml
contains its own service bindings, those services must also be mounted in the root worker (i.e. inwrangler.toml
not./auth/wrangler.toml
). Nested mounts are not supported.
Builds:
- When running your worker's build script, Miniflare will set the environment
variable
MINIFLARE=1
. Closes issue #65, thanks @maraisr. - Added an alias,
-B
, for the--build-command
option - Multiple build watch paths can now be specified. If any of them change, your worker will rebuild and reload.
- Pass the
--env
flag towrangler build
when--wrangler-env
is set fortype = "webpack"
/"rust"
builds - Fixed an issue where workers would not rebuild if the build watch path started
with
./
. Closes issue #53, thanks @janat08.
Standards:
- Added support for
crypto.randomUUID()
- Added support for
structuredClone
. Note thetransfer
option is only supported on Node.js >= 17. - Added support for
queueMicrotask
- Added support for the
NODE-ED25519
algorithm tocrypto.subtle.sign()
andcrypto.subtle.verify()
- Added support for
AbortSignal.timeout()
- Added support for
crypto.DigestStream
- Added support for
scheduler.wait()
- Added support for
FixedLengthStream
. Closes issue #123, thanks @vlovich. - Throw an error when attempting to create a new
TextDecoder
with a non-UTF-8 encoding - Throw errors when attempting to use
FetchEvent
/ScheduledEvent
methods with incorrectly boundthis
- Throw errors when attempting to call
respondWith()
twice, or after thefetch
handler has finished executing synchronously. Closes issue #63, thanks @Kikobeats. - Added support for the
unhandledrejection
andrejectionhandled
events - Throw an error (with a suggested fix) when trying to access an
env
binding globally in modules mode - Throw errors when trying to use
addEventListener()
,removeEventListener()
anddispatchEvent()
globals in modules mode - Split the
FetchError: No fetch handler responded and unable to proxy request to upstream?
error into more specific errors with suggested fixes - Added the
non-standard
Headers#getAll()
method. This can only be used with theSet-Cookie
header. - Switch to a
more spec-compliant
fetch
implementation, and getcrypto
,EventTarget
and Web Streams from Node.js. Closes issues #56 and #59, thanks @jasnell, @jonathannorris and @SupremeTechnopriest. - Added support for the
Response#encodeBody
property. If this is omitted or set toauto
,Response
s with aContent-Encoding
header that includesgzip
,deflate
orbr
will be automatically encoded. Closes issue #72, thanks @SupremeTechnopriest. - Return a non-
opaque
Response
containing headers when fetching with aredirect
mode set tomanual
in response to a redirect, closes issue #133, thanks @hansede, @vzaramel and @hnrqer. - Set the
redirect
mode of incoming requests tomanual
, matching the behaviour of the Workers runtime - Remove extra headers not sent by Cloudflare Workers with
fetch
requests. Closes issue #139, thanks @dfcowell. Request
/Response
body
s are now byte streams, allowing them to be read with bring-your-own-buffer readers- Throw an error when attempting to construct a WebSocket response with a status
other than
101
- Throw an error when attempting to clone a WebSocket response
- Added support for the non-standard
ReadableStreamBYOBReader#readAtLeast(size, buffer)
method - Include
File
in the Miniflare sandbox. Closes issue #66, thanks @tranzium.
Durable Objects:
- Added input and output gates for ensuring consistency without explicit transactions
- Added write coalescing for
put
/delete
without interleavingawait
s for automatic atomic writes - Added the
DurableObjectState#blockConcurrencyWhile(callback)
method. This prevents newfetch
events being delivered to your object whilst the callback runs. Closes issue #45, thanks @gmencz. - Added the
DurableObjectId#equals(id)
method for comparing if 2 Durable Object IDs have the same hex-ID - Automatically resolve relative URLs passed to
DurableObjectStub#fetch(input, init?)
againsthttps://fast-host
. Closes issue #27, thanks @halzy. - Throw an error if the string passed to
DurableObjectNamespace#idFromString(hexId)
is not 64 hex digits - Throw an error if the hex-ID passed to
DurableObjectNamespace#idFromString(hexId)
is for a different Durable Object - Throw an error if the ID passed to
DurableObjectNamespace#get(id)
is for a different Durable Object - Throw an error when keys are greater than
2KiB
orundefined
- Throw an error when values are greater than
128KiB
- Throw an error when attempting to
get
,put
ordelete
more than128
keys, or when attempting to modify more than128
keys in a transaction - Throw an error when attempting to
put
anundefined
value - Throw an error when attempting to list keys with a negative
limit
- Throw an error when attempting to perform an operation in a rolledback transaction or in a transaction that has already committed
- Throw an error when attempting to call
deleteAll()
in a transaction - Throw an error when a Durable Object
fetch
handler doesn't return aResponse
- Use the same V8 serialization as Cloudflare Workers to store values
- Fixed an issue where keys added in a transaction callback were not reported as deleted in the same transaction
- Fixed an issue where keys added in a transaction callback were not included in the list of keys in the same transaction
HTMLRewriter:
- Remove
Content-Length
header fromHTMLRewriter
transformedResponse
s - Don't start transforming until transformed
Response
body is needed - Throw an error when attempting to transform body streams containing non-ArrayBuffer/ArrayBufferView chunks
HTTP Server:
-
Added a live reload feature, that automatically refreshes your browser when your worker reloads. For this to work, pass the
--live-reload
option, and return an HTML response containing a<body>
tag with theContent-Type
set totext/html
. See β‘οΈ Live Reload for more details.addEventListener("fetch", (event) => { const body = ` <!DOCTYPE html> <html> <body> <p>Try update me!</p> </body> </html> `; const res = new Response(body, { headers: { "Content-Type": "text/html; charset=utf-8" }, }); event.respondWith(res); });
-
Added
--open
/-O
option that automatically opens your browser once your worker is running. You can optionally specify a different URL to open with--open https://example.com
. Closes issue #121, thanks @third774 for the suggestion. -
Automatically fetch the incoming
Request#cf
object from a trusted Cloudflare endpoint, so the values are the same as you'd get for real. Closes issue #61, thanks @aaronsdevera and @Electroid. -
Added a
metaProvider
option that allows you fetch metadata for an incomingRequest
:const mf = new Miniflare({ async metaProvider(req) { return { forwardedProto: req.headers["X-Forwarded-Proto"], realIp: req.headers["X-Forwarded-For"], cf: { // Could get these from a geo-IP database colo: "SFO", country: "US", // ... }, }; }, });
-
Split out the Node request to
Request
object conversion logic into aconvertNodeRequest(req, meta?)
function. You can import this from@miniflare/http-server
. -
Only return a pretty-error page when the request
Accept
header includestext/html
-
Added a new
Miniflare#startServer(options?)
method that starts an HTTP server using the configuredport
andhost
.options
can be ahttp.ServerOptions
orhttps.ServerOptions
object. Closes issue #39, thanks @amlwwalker -
Include a default
Content-Type
header oftext/plain
inResponse
s. Closes issue #57, thanks @Rysertio.
Jest Environment:
- Added a custom Jest test environment, allowing you to run unit tests in the Miniflare sandbox, with isolated storage for each test. See π€Ή Jest Environment for more details.
KV:
- Throw an error when keys are empty,
.
,..
,undefined
, or greater than512B
when UTF-8 encoded - Throw an error when values are greater than
25MiB
- Throw an error when metadata is greater than
1KiB
- Throw an error when the
cacheTtl
option is less than60s
- Throw an error when
expirationTtl
is non-numeric, less than or equal 0, or less than60s
- Throw an error when
expiration
is non-numeric, less than or equal the current time, or less than60s
in the future - Throw an error when the
limit
passed toKVNamespace#list()
is non-numeric, less than or equal0
, or greater than1000
Scheduler:
- Moved the
/.mf/scheduled
endpoint for triggering scheduled events to/cdn-cgi/mf/scheduled
. Closes issue #42, thanks @ObsidianMinor. - Switched the CRON validation and scheduling package from
node-cron
tocron-schedule
. This improves error messages for invalid CRON expressions, and removes a transitive dependency onmoment-timezone
, reducing the installation size by 5MB.
Workers Sites:
- Added support for the new
__STATIC_CONTENT_MANIFEST
text module allowing you to use Workers Sites in modules mode
Web Sockets:
- Added support for sending/receiving binary messages. Closes issue #67, thanks @NostalgiaRunner.
- Removed the
WebSocket#readyState
property. Closes issue #47, thanks @aboodman. - Wait for worker response before opening WebSocket in client, closes issue #88, thanks @TimTinkers.
http
andhttps
protocols are now required for WebSocket upgrades viafetch
as per the workers runtime- Throw an error when attempting to use a
WebSocket
in aResponse
that has already been used - Throw an error when attempting to use a
WebSocket
in aResponse
after callingaccept()
on it - Throw an error when attempting to construct a
WebSocket
using theWebSocket
constructor - Throw an error when attempting to call
WebSocket#send()
orWebSocket#close()
without first callingaccept()
. Closes issue #43, thanks @aboodman. - Throw an error when attempting to call
WebSocket#send()
after callingclose()
- Throw an error when attempting to call
WebSocket#close()
on an already closed WebSocket - Throw an error when attempting to call
WebSocket#close()
with an invalid close code - Make WebSocket event constructors more spec-compliant
- Fixed linking of modules with cyclic imports, allowing new Rust workers to be run with Miniflare. Closes issue #41, thanks @nuvanti.
- Fixed handling of
ArrayBufferView
s asResponse
bodies
- Added
Event
andEventTarget
to the sandbox. The global scope andWebSocket
now inherit fromEventTarget
soremoveEventListener
is now supported. Closes issue #18, thanks @jayphelps. - Added workers' uncompressed size to logs, closes issue #23, thanks @ItsWendell
- Switch to lighter dependencies, thanks @lukeed. There's still lots of work to do here for the next major release.
- Require the
GET
method for WebSocket upgrades, closes issue #25, thanks @ItsWendell - Added
WebSocket
to the sandbox, closes issue #30, thanks @ItsWendell. Note you still need to useWebSocketPair
andfetch
to set up WebSocket connections. See βοΈ WebSockets for more details. - Fixed caching with
URL
request keys, closes issue #33, thanks @TimTinkers - Disable the watcher whilst rebuilding, closes issue #34, thanks @TimTinkers
- Added an option to disable default and named caches. When disabled, the caches will still be available in the sandbox, they just won't cache anything. Thanks @frandiox for the suggestion. See β¨ Cache for more details.
- Added the corresponding
wrangler.toml
key for the--disable-updater
flag:miniflare.disable_updater
- Fixed the
package.json
file path the update checker checked against
- Responses are now streamed when using the built-in HTTP(S) server
- Return values of Durable Object transaction closures are now propagated as the
return value of the
transaction
call
- Upgraded
html-rewriter-wasm
to version0.3.2
, fixingasync
handler support, closeshtml-rewriter-wasm
issue #1
- Upgraded
html-rewriter-wasm
to version0.3.1
, fixing the return type ofElement.attributes
- Switched to a
lol-html
-based WebAssembly implementation ofHTMLRewriter
for a more accurate simulation of the real Workers environment. See π HTMLRewriter for more details. - Added HTTPS support for local development, thanks @RichiCoder1 for the suggestion (#12). See π» Using the CLI and π§° Using the API for more details.
- When using the CLI, the
--watch
flag is now assumed if--build-watch-path
is set, thanks @evanderkoogh for the PR (#8) - Added source maps to
CommonJS
module transformation
- Switched to real values for the
cf
property, thanks @chase for the PR (#11) - Upgraded the TOML parser to support dotted keys, thanks @leader22 for the PR (#13)
- Added
CryptoKey
to the sandbox, thanks @mosch for the PR (#14)
- Added Redis persistence support for π¦ KV, β¨ Cache and π Durable Objects
- Added support for loading scripts from
package.json
, closes issue #7. See π» Using the CLI and β‘οΈ Developing with esbuild for more details. - Added
FormData
to the sandbox, closes issue #6 - Added an automatic update checker. See π» Using the CLI for more details.
- π Modules mode is now always enabled when specifying π Durable Objects bindings
- Fixed Windows support, closes issue #10
- Fixed issue where scripts were not reloaded correctly when editing script path
in
wrangler.toml
. Scripts are now always reloaded on options change.Miniflare.reloadScript()
is now deprecated. You should useMiniflare.reloadOptions()
instead.
- Added support for namespaced caches with
caches.open
. See β¨ Cache for more details.
- Fixed
/usr/bin/env: 'node --experimental-vm-modules': No such file or directory
error when running the CLI in Linux. See π» Using the CLI for more details.
-
The first and only argument to the
Miniflare
constructor is now an object. Scripts should be specified via thescript
option for strings and thescriptPath
option for files:// Previous version import vm from "vm"; import { Miniflare } from "miniflare"; const mf1 = new Miniflare( new vm.Script(`addEventListener("fetch", (event) => { ... })`), { kvPersist: true } ); const mf2 = new Miniflare("script.js", { kvPersist: true });
// New version import { Miniflare } from "miniflare"; const mf1 = new Miniflare({ script: `addEventListener("fetch", (event) => { ... })`, kvPersist: true, }); const mf2 = new Miniflare({ scriptPath: "script.js", kvPersist: true, });
-
The
Miniflare.getNamespace
method has been renamed toMiniflare.getKVNamespace
-
Logged errors will now throw a
MiniflareError
if no log is provided -
When using file system KV persistence, key names are now sanitised to replace special characters such as
:
,/
, and\
. Reading keys containing these characters may now returnnull
if a value was stored in the previous version.
- Added support for π Modules (requires
--experimental-vm-modules
flag) - Added support for π Durable Objects
- Added support for βοΈ Web Sockets (client and server)
- Added support for π Builds (custom
builds and
webpack
/rust
Wrangler builds) - Added support for βοΈ WebAssembly
- Added support for π HTMLRewriter
- Made CLI
script
parameter optional, it can now be inferred in some cases fromwrangler.toml
- Added
host
option (--host
/-H
flag) for restricting hosts the HTTP server listens on - Added
Miniflare.dispose
method for cleaning up file watcher - Added
CF-*
headers andcf
object to HTTP server requests - Added
cron
property to β° Scheduled Events - Added manual triggering for
β° Scheduled Events via
/.mf/scheduled
HTTP endpoint - Added pretty error page powered by Youch
- Added many more tests
- Fixed error if options object (containing
type
andcacheTtl
properties) passed as second parameter to KVget
method, closes issue #3 - Fixed error if
ArrayBuffer
passed asdata
tocrypto.subtle.digest("md5", data)
- Fixed handling of
ignoreMethod
option forCache
match
anddelete
- Disabled edge caching when using Workers Sites, files are now always loaded from disk
- Provided
Set
andWeakSet
from Miniflare's realm to sandbox, removingPromise
, so(async () => {})() instanceof Promise
evaluates totrue
- Depend on
@mrbbot/node-fetch
from npm instead of GitHub, closes issue #2
Initial Release
- Added support for π¨ Fetch Events
- Added support for β° Scheduled Events
- Added support for π Variables and Secrets
- Added support for π¦ KV
- Added support for β¨ Cache
- Added support for π Workers Sites
- Added support for πΊ Source Maps