世祺 0423d5801c Initial commit (by Create-Cloudflare CLI) | 1 year ago | |
---|---|---|
.. | ||
dist | 1 year ago | |
README.md | 1 year ago | |
bootstrap.js | 1 year ago | |
package.json | 1 year ago |
Miniflare 3 is a simulator for developing and testing
Cloudflare Workers, powered by
workerd
.
:warning: Miniflare 3 is API-only, and does not expose a CLI. Use Wrangler with
wrangler dev
to develop your Workers locally with Miniflare 3.
$ npm install miniflare --save-dev
import { Miniflare } from "miniflare";
// Create a new Miniflare instance, starting a workerd server
const mf = new Miniflare({
script: `addEventListener("fetch", (event) => {
event.respondWith(new Response("Hello Miniflare!"));
})`,
});
// Send a request to the workerd server, the host is ignored
const response = await mf.dispatchFetch("http://localhost:8787/");
console.log(await response.text()); // Hello Miniflare!
// Cleanup Miniflare, shutting down the workerd server
await mf.dispose();
type Awaitable<T>
T | Promise<T>
Represents a value that can be await
ed. Used in callback types to allow
Promise
s to be returned if necessary.
type Json
string | number | boolean | null | Record<string, Json> | Json[]
Represents a JSON-serialisable value.
type ModuleRuleType
"ESModule" | "CommonJS" | "Text" | "Data" | "CompiledWasm"
Represents how a module's contents should be interpreted.
"ESModule"
: interpret as
ECMAScript module"CommonJS"
: interpret as
CommonJS module"Text"
: interpret as UTF8-encoded data, expose in runtime with
string
-typed default
export"Data"
: interpret as arbitrary binary data, expose in runtime with
ArrayBuffer
-typed default
export"CompiledWasm"
: interpret as binary WebAssembly module data, expose in
runtime with WebAssembly.Module
-typed default
exportinterface ModuleDefinition
Represents a manually defined module.
type: ModuleRuleType
How this module's contents should be interpreted.
path: string
Path of this module. The module's "name" will be obtained by converting this
to a relative path. The original path will be used to read contents
if it's
omitted.
contents?: string | Uint8Array
Contents override for this module. Binary data should be passed as
Uint8Array
s. If omitted, will be read from path
.
interface ModuleRule
Represents a rule for identifying the ModuleRuleType
of automatically located
modules.
type: ModuleRuleType
How to interpret modules that match the include
patterns.
include: string[]
Glob patterns to match located module paths against (e.g. ["**/*.txt"]
).
fallthrough?: boolean
If true
, ignore any further rules of this type
. This is useful for
disabling the built-in ESModule
and CommonJS
rules that match *.mjs
and
*.js
/*.cjs
files respectively.
type Persistence
boolean | string | undefined
Represents where data should be persisted, if anywhere.
undefined
or false
, data will be stored in-memory and only
persist between Miniflare#setOptions()
calls, not restarts nor
new Miniflare
instances.true
, data will be stored on the file-system, in the $PWD/.mf
directory.memory:
, data will be stored in-memory as above.file:
, data will be stored on the file-system, in the
specified directory (e.g. file:///path/to/directory
). If the unsanitise
search parameter is true
, path sanitisation will be disabled.string
, data will be stored on the
file-system, using the value as the directory path.enum LogLevel
NONE, ERROR, WARN, INFO, DEBUG, VERBOSE
Controls which messages Miniflare logs. All messages at or below the selected level will be logged.
interface LogOptions
prefix?: string
String to add before the level prefix when logging messages. Defaults to mf
.
suffix?: string
String to add after the level prefix when logging messages.
class Log
constructor(level?: LogLevel, opts?: LogOptions)
Creates a new logger that logs all messages at or below the specified level to
the console
.
error(message: Error)
Logs a message at the ERROR
level. If the constructed log level
is less
than ERROR
, throw
s the message
instead.
warn(message: string)
Logs a message at the WARN
level.
info(message: string)
Logs a message at the INFO
level.
debug(message: string)
Logs a message at the DEBUG
level.
verbose(message: string)
Logs a message at the VERBOSE
level.
class NoOpLog extends Log
constructor()
Creates a new logger that logs nothing to the console
, and always throw
s
message
s logged at the ERROR
level.
interface QueueConsumerOptions
maxBatchSize?: number
Maximum number of messages allowed in each batch. Defaults to 5
.
maxBatchTimeout?: number
Maximum number of seconds to wait for a full batch. If a message is sent, and
this timeout elapses, a partial batch will be dispatched. Defaults to 1
.
maxRetries?: number
Maximum number of times to retry dispatching a message, if handling it throws,
or it is explicitly retried. Defaults to 2
.
deadLetterQueue?: string
Name of another Queue to send a message on if it fails processing after
maxRetries
. If this isn't specified, failed messages will be discarded.
interface WorkerOptions
Options for an individual Worker/"nanoservice". All bindings are accessible on
the global scope in service-worker format Workers, or via the 2nd env
parameter in module format Workers.
name?: string
Unique name for this worker. Only required if multiple workers
are
specified.
script?: string
JavaScript code for this worker. If this is a service worker format Worker, it
must not have any imports. If this is a modules format Worker, it must not
have any npm imports, and modules: true
must be set. If it does have
imports, scriptPath
must also be set so Miniflare knows where to resolve
them relative to.
scriptPath?: string
Path of JavaScript entrypoint. If this is a service worker format Worker, it
must not have any imports. If this is a modules format Worker, it must not
have any npm imports, and modules: true
must be set.
modules?: boolean | ModuleDefinition[]
If true
, Miniflare will treat script
/scriptPath
as an ES Module and
automatically locate transitive module dependencies according to
modulesRules
. Note that automatic location is not perfect: if the
specifier to a dynamic import()
or require()
is not a string literal, an
exception will be thrown.
If set to an array, modules can be defined manually. Transitive dependencies
must also be defined. Note the first module must be the entrypoint and have
type "ESModule"
.
modulesRoot?: string
If modules
is set to an array, modules' "name"s will be their path
s
relative to this value. This ensures file paths in stack traces are correct.
modulesRules?: ModuleRule[]
Rules for identifying the ModuleRuleType
of automatically located modules
when modules: true
is set. Note the following default rules are always
included at the end:
[
{ type: "ESModule", include: ["**/*.mjs"] },
{ type: "CommonJS", include: ["**/*.js", "**/*.cjs"] },
]
If
script
andscriptPath
are set, andmodules
is set to an array,modules
takes priority for a Worker's code, followed byscript
, thenscriptPath
.
compatibilityDate?: string
Compatibility date to use for this Worker. Defaults to a date far in the past.
compatibilityFlags?: string[]
Compatibility flags to use for this Worker.
bindings?: Record<string, Json>
Record mapping binding name to arbitrary JSON-serialisable values to inject as bindings into this Worker.
wasmBindings?: Record<string, string>
Record mapping binding name to paths containing binary WebAssembly module data
to inject as WebAssembly.Module
bindings into this Worker.
textBlobBindings?: Record<string, string>
Record mapping binding name to paths containing UTF8-encoded data to inject as
string
bindings into this Worker.
dataBlobBindings?: Record<string, string>
Record mapping binding name to paths containing arbitrary binary data to
inject as ArrayBuffer
bindings into this Worker.
serviceBindings?: Record<string, string | { network: Network } | { external: ExternalServer } | { disk: DiskDirectory } | (request: Request) => Awaitable<Response>>
Record mapping binding name to service designators to inject as
{ fetch: typeof fetch }
service bindings
into this Worker.
string
, requests will be dispatched to the Worker
with that name
.{ network: { ... } }
, where
network
is a
workerd
Network
struct,
requests will be dispatched according to the fetch
ed URL.{ external: { ... } }
where
external
is a
workerd
ExternalServer
struct,
requests will be dispatched to the specified remote server.{ disk: { ... } }
where disk
is a
workerd
DiskDirectory
struct,
requests will be dispatched to an HTTP service backed by an on-disk
directory.If the designator is a function, requests will be dispatched to your custom handler. This allows you to access data and functions defined in Node.js from your Worker.
outboundService?: string | { network: Network } | { external: ExternalServer } | { disk: DiskDirectory } | (request: Request) => Awaitable<Response>
Dispatch this Worker's global fetch()
and connect()
requests to the
configured service. Service designators follow the same rules above for
serviceBindings
.
fetchMock?: import("undici").MockAgent
An undici
MockAgent
to
dispatch this Worker's global fetch()
requests through.
:warning:
outboundService
andfetchMock
are mutually exclusive options. At most one of them may be specified per Worker.
routes?: string[]
Array of route patterns for this Worker. These follow the same routing rules as deployed Workers. If no routes match, Miniflare will fallback to the Worker defined first.
cache?: boolean
If false
, default and named caches will be disabled. The Cache API will
still be available, it just won't cache anything.
cacheWarnUsage?: boolean
If true
, the first use of the Cache API will log a warning stating that the
Cache API is unsupported on workers.dev
subdomains.
durableObjects?: Record<string, string | { className: string, scriptName?: string }>
Record mapping binding name to Durable Object class designators to inject as
DurableObjectNamespace
bindings into this Worker.
string
, it should be the name of a class
exported
by this Worker.scriptName
is undefined
, className
should be the name of a class
exported by this Worker.className
should be the name of a class
exported by the
Worker with a name
of scriptName
.kvNamespaces?: Record<string, string> | string[]
Record mapping binding name to KV namespace IDs to inject as KVNamespace
bindings into this Worker. Different Workers may bind to the same namespace ID
with different binding names. If a string[]
of binding names is specified,
the binding name and KV namespace ID are assumed to be the same.
sitePath?: string
Path to serve Workers Sites files from. If set, __STATIC_CONTENT
and
__STATIC_CONTENT_MANIFEST
bindings will be injected into this Worker. In
modules mode, __STATIC_CONTENT_MANIFEST
will also be exposed as a module
with a string
-typed default
export, containing the JSON-stringified
manifest. Note Workers Sites files are never cached in Miniflare.
siteInclude?: string[]
If set, only files with paths matching these glob patterns will be served.
siteExclude?: string[]
If set, only files with paths not matching these glob patterns will be served.
r2Buckets?: Record<string, string> | string[]
Record mapping binding name to R2 bucket names to inject as R2Bucket
bindings into this Worker. Different Workers may bind to the same bucket name
with different binding names. If a string[]
of binding names is specified,
the binding name and bucket name are assumed to be the same.
d1Databases?: Record<string, string> | string[]
Record mapping binding name to D1 database IDs to inject as Fetcher
bindings
into this Worker. Note these bindings must be wrapped with a facade to provide
the expected D1Database
API. Different Workers may bind to the same database
ID with different binding names. If a string[]
of binding names is
specified, the binding name and database ID are assumed to be the same.
:warning: Queues are only supported with Node.js 18 or above.
queueProducers?: Record<string, string> | string[]
Record mapping binding name to queue names to inject as WorkerQueue
bindings
into this Worker. Different Workers may bind to the same queue name with
different binding names. If a string[]
of binding names is specified, the
binding name and queue name are assumed to be the same.
queueConsumers?: Record<string, QueueConsumerOptions> | string[]
Record mapping queue name to consumer options. Messages enqueued on the
corresponding queues will be dispatched to this Worker. Note each queue can
have at most one consumer. If a string[]
of queue names is specified,
default consumer options will be used.
Not yet supported
interface SharedOptions
Options shared between all Workers/"nanoservices".
host?: string
Hostname that the workerd
server should listen on. Defaults to 127.0.0.1
.
port?: number
Port that the workerd
server should listen on. Tries to default to 8787
,
but falls back to a random free port if this is in use. Note if a manually
specified port is in use, Miniflare throws an error, rather than attempting to
find a free port.
https?: boolean
If true
, start an HTTPS server using a pre-generated self-signed certificate
for localhost
. Note this certificate is not valid for any other hostnames or
IP addresses. If you need to access the HTTPS server from another device,
you'll need to generate your own certificate and use the other https*
options below.
$ openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem
new Miniflare({
httpsKeyPath: "key.pem",
httpsCertPath: "cert.pem",
});
httpsKey?: string
When one of httpsCert
or httpCertPath
is also specified, starts an HTTPS
server using the value of this option as the PEM encoded private key.
httpsKeyPath?: string
When one of httpsCert
or httpCertPath
is also specified, starts an HTTPS
server using the PEM encoded private key stored at this file path.
httpsCert?: string
When one of httpsKey
or httpsKeyPath
is also specified, starts an HTTPS
server using the value of this option as the PEM encoded certificate chain.
httpsCertPath?: string
When one of httpsKey
or httpsKeyPath
is also specified, starts an HTTPS
server using the PEM encoded certificate chain stored at this file path.
inspectorPort?: number
Port that workerd
should start a DevTools inspector server on. Visit
chrome://inspect
in a Chromium-based browser to connect to this. This can be
used to see detailed console.log
s, profile CPU usage, and will eventually
allow step-through debugging.
verbose?: boolean
Enable workerd
's --verbose
flag for verbose logging. This can be used to
see simplified console.log
s.
log?: Log
Logger implementation for Miniflare's errors, warnings and informative messages.
upstream?: string
URL to use as the origin for incoming requests. If specified, all incoming
request.url
s will be rewritten to start with this string. This is especially
useful when testing Workers that act as a proxy, and not as origins
themselves.
cf?: boolean | string | Record<string, any>
Controls the object returned from incoming Request
's cf
property.
true
, a real cf
object will be fetched from a trusted
Cloudflare endpoint and cached in node_modules/.mf
for 30 daysIf set to a string
, a real cf
object will be fetched and cached at the
provided path for 30 days
liveReload?: boolean
If true
, Miniflare will inject a script into HTML responses that
automatically reloads the page in-browser whenever the Miniflare instance's
options are updated.
cachePersist?: Persistence
Where to persist data cached in default or named caches. See docs for
Persistence
.
durableObjectsPersist?: Persistence
Where to persist data stored in Durable Objects. See docs for Persistence
.
kvPersist?: Persistence
Where to persist data stored in KV namespaces. See docs for Persistence
.
r2Persist?: Persistence
Where to persist data stored in R2 buckets. See docs for Persistence
.
d1Persist?: Persistence
Where to persist data stored in D1 databases. See docs for Persistence
.
Not yet supported
type MiniflareOptions
SharedOptions & (WorkerOptions | { workers: WorkerOptions[] })
Miniflare accepts either a single Worker configuration or multiple Worker
configurations in the workers
array. When specifying an array of Workers, the
first Worker is designated the entrypoint and will receive all incoming HTTP
requests. Some options are shared between all workers and should always be
defined at the top-level.
class Miniflare
constructor(opts: MiniflareOptions)
Creates a Miniflare instance and starts a new workerd
server. Note unlike
Miniflare 2, Miniflare 3 always starts a HTTP server listening on the
configured host
and port
: there are no createServer
/startServer
functions.
setOptions(opts: MiniflareOptions)
Updates the configuration for this Miniflare instance and restarts the
workerd
server. Note unlike Miniflare 2, this does not merge the new
configuration with the old configuration.
ready: Promise<URL>
Returns a Promise
that resolves with a http
URL
to the workerd
server
once it has started and is able to accept requests.
dispatchFetch(input: RequestInfo, init?: RequestInit): Promise<Response>
Sends a HTTP request to the workerd
server, dispatching a fetch
event in
the entrypoint Worker. Returns a Promise
that resolves with the response.
Note that this implicitly waits for the ready
Promise
to resolve, there's
no need to do that yourself first. Additionally, the host of the request's URL
is always ignored and replaced with the workerd
server's.
dispose(): Promise<void>
Cleans up the Miniflare instance, and shuts down the workerd
server. Note
that after this is called, setOptions
and dispatchFetch
cannot be called.