• Stars
    star
    3,719
  • Rank 11,871 (Top 0.3 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created over 3 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

๐Ÿ”ฅ Fully-local simulator for Cloudflare Workers. For the latest version, see https://github.com/cloudflare/workers-sdk/tree/main/packages/miniflare.

๐Ÿ”ฅ Miniflare

Miniflare is a simulator for developing and testing Cloudflare Workers.

  • ๐ŸŽ‰ Fun: develop workers easily with detailed logging, file watching and pretty error pages supporting source maps.
  • ๐Ÿ”‹ Full-featured: supports most Workers features, including KV, Durable Objects, WebSockets, modules and more.
  • โšก Fully-local: test and develop Workers without an internet connection. Reload code on change quickly.

It's an alternative to wrangler dev, written in TypeScript, that runs your workers in a sandbox implementing Workers' runtime APIs.

See https://miniflare.dev for more detailed documentation.

Features

  • ๐Ÿ“จ Fetch Events (with HTTP(S) server and manual dispatch)
  • โฐ Scheduled Events (with cron triggering and manual dispatch)
  • ๐Ÿ”‘ Variables and Secrets with .env Files
  • ๐Ÿ“š Modules Support
  • ๐Ÿ“ฆ KV (with optional persistence)
  • ๐Ÿชฃ R2 (with optional persistence)
  • โœจ Cache (with optional persistence)
  • ๐Ÿ“Œ Durable Objects (with optional persistence)
  • ๐ŸŒ Workers Sites
  • โœ‰๏ธ WebSockets
  • ๐Ÿ›  Custom & Wrangler Builds Support
  • โš™๏ธ WebAssembly Support
  • ๐Ÿ—บ Source Map Support
  • ๐Ÿ•ธ Web Standards: Base64, Timers, Fetch, Encoding, URL, Streams, Crypto
  • ๐Ÿ“„ HTMLRewriter
  • โšก๏ธ Live Reload on File Changes
  • ๐Ÿ“… Compatibility Dates/Flags Support
  • ๐Ÿ”Œ Multiple Workers Support
  • ๐Ÿคน Custom Jest Environment (with isolated per-test storage)
  • ๐Ÿ’ช Written in TypeScript

Install

Miniflare is installed using npm:

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

Using the CLI

$ 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

Using the API

import { Miniflare } from "miniflare";

const mf = new Miniflare({
  script: `
  addEventListener("fetch", (event) => {
    event.respondWith(new Response("Hello Miniflare!"));
  });
  `,
});
const res = await mf.dispatchFetch("http://localhost:8787/");
console.log(await res.text()); // Hello Miniflare!

CLI Reference

Usage: miniflare [script] [options]

Core Options:
 -h, --help              Show help                                                   [boolean]
 -v, --version           Show version number                                         [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                                 [array:TYPE=GLOB]
     --compat-date       Opt into backwards-incompatible changes from                 [string]
     --compat-flag       Control specific backwards-incompatible changes               [array]
     --usage-model       Usage model (bundled by default)                             [string]
 -u, --upstream          URL of upstream origin                                       [string]
 -w, --watch             Watch files for changes                                     [boolean]
 -d, --debug             Enable debug logging                                        [boolean]
 -V, --verbose           Enable verbose logging                                      [boolean]
     --(no-)update-check Enable update checker (enabled by default)                  [boolean]
     --repl              Enable interactive REPL                                     [boolean]
     --root              Path to resolve files relative to                            [string]
     --mount             Mount additional named workers                [array:NAME=PATH[@ENV]]
     --name              Name of service                                              [string]
     --route             Route to respond with this worker on                          [array]
     --global-async-io   Allow async I/O outside handlers                            [boolean]
     --global-timers     Allow setting timers outside handlers                       [boolean]
     --global-random     Allow secure random generation outside handlers             [boolean]
     --actual-time       Always return correct time from Date methods                [boolean]
     --inaccurate-cpu    Log inaccurate CPU time measurements                        [boolean]

HTTP Options:
 -H, --host              Host for HTTP(S) server to listen on                         [string]
 -p, --port              Port for HTTP(S) server to listen on                         [number]
 -O, --open              Automatically open browser to URL                    [boolean/string]
     --https             Enable self-signed HTTPS (with optional cert path)   [boolean/string]
     --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]
     --(no-)cf-fetch     Path for cached Request cf object from Cloudflare    [boolean/string]
     --live-reload       Reload HTML pages whenever worker is reloaded               [boolean]

Scheduler Options:
 -t, --cron              CRON expression for triggering scheduled events               [array]

Build Options:
 -B, --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                  [array]

KV Options:
 -k, --kv                KV namespace to bind                                          [array]
     --kv-persist        Persist KV data (to optional path)                   [boolean/string]

R2 Options:
 -r, --r2                R2 bucket to bind                                             [array]
     --r2-persist        Persist R2 data (to optional path)                   [boolean/string]

Durable Objects Options:
 -o, --do                Durable Object to bind                     [array:NAME=CLASS[@MOUNT]]
     --do-persist        Persist Durable Object data (to optional path)       [boolean/string]
     --(no-)do-alarms    Enable Durable Object alarms (enabled by default)           [boolean]

Cache Options:
     --(no-)cache        Enable default/named caches (enabled by default)            [boolean]
     --cache-persist     Persist cached data (to optional path)               [boolean/string]

Sites Options:
 -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]

Bindings Options:
 -e, --env               Path to .env file                                            [string]
 -b, --binding           Binds variable/secret to environment                [array:KEY=VALUE]
     --global            Binds variable/secret to global scope               [array:KEY=VALUE]
     --wasm              WASM module to bind                                 [array:NAME=PATH]
     --text-blob         Text blob to bind                                   [array:NAME=PATH]
     --data-blob         Data blob to bind                                   [array:NAME=PATH]
 -S, --service           Mounted service to bind                      [array:NAME=MOUNT[@ENV]]

Acknowledgements

Miniflare was created by Brendan Coll.

Many thanks to dollarshaveclub/cloudworker and gja/cloudflare-worker-local for inspiration.

Durable Object's transactions are implemented using Optimistic Concurrency Control (OCC) as described in "On optimistic methods for concurrency control." ACM Transactions on Database Systems. Thanks to Alistair O'Brien for helping the Miniflare creator understand this.

More Repositories

1

pingora

A library for building fast, reliable and evolvable network services.
Rust
20,561
star
2

quiche

๐Ÿฅง Savoury implementation of the QUIC transport protocol and HTTP/3
Rust
9,191
star
3

cfssl

CFSSL: Cloudflare's PKI and TLS toolkit
Go
8,049
star
4

workerd

The JavaScript / Wasm runtime that powers Cloudflare Workers
C++
6,175
star
5

boringtun

Userspace WireGuardยฎ Implementation in Rust
Rust
6,001
star
6

cloudflared

Cloudflare Tunnel client (formerly Argo Tunnel)
Go
5,870
star
7

flan

A pretty sweet vulnerability scanner
Python
3,910
star
8

wrangler-legacy

๐Ÿค  Home to Wrangler v1 (deprecated)
Rust
3,233
star
9

cloudflare-docs

Cloudflareโ€™s documentation
MDX
3,009
star
10

tableflip

Graceful process restarts in Go
Go
2,549
star
11

workers-rs

Write Cloudflare Workers in 100% Rust via WebAssembly
Rust
2,478
star
12

workers-sdk

โ›…๏ธ Home to Wrangler, the CLI for Cloudflare Workersยฎ
TypeScript
2,464
star
13

wildebeest

Wildebeest is an ActivityPub and Mastodon-compatible server
TypeScript
2,042
star
14

gokey

A simple vaultless password manager in Go
Go
1,836
star
15

ebpf_exporter

Prometheus exporter for custom eBPF metrics
C
1,639
star
16

cloudflare-go

The official Go library for the Cloudflare API
Go
1,477
star
17

lol-html

Low output latency streaming HTML parser/rewriter with CSS selector-based API
Rust
1,459
star
18

orange

TypeScript
1,400
star
19

redoctober

Go server for two-man rule style file encryption and decryption.
Go
1,373
star
20

cf-ui

๐Ÿ’Ž Cloudflare UI Framework
JavaScript
1,297
star
21

sslconfig

Cloudflare's Internet facing SSL configuration
1,287
star
22

foundations

Cloudflare's Rust service foundations library.
Rust
1,273
star
23

next-on-pages

CLI to build and develop Next.js apps for Cloudflare Pages
TypeScript
1,184
star
24

hellogopher

Hellogopher: "just clone and make" your conventional Go project
Makefile
1,153
star
25

production-saas

(WIP) Example SaaS application built in public on the Cloudflare stack!
TypeScript
1,114
star
26

bpftools

BPF Tools - packet analyst toolkit
Python
1,087
star
27

cloudflare-blog

Cloudflare Blog code samples
C
1,065
star
28

templates

A collection of starter templates and examples for Cloudflare Workers and Pages
JavaScript
996
star
29

wrangler-action

๐Ÿง™โ€โ™€๏ธ easily deploy cloudflare workers applications using wrangler and github actions
TypeScript
993
star
30

circl

CIRCL: Cloudflare Interoperable Reusable Cryptographic Library
Go
970
star
31

cf-terraforming

A command line utility to facilitate terraforming your existing Cloudflare resources.
Go
966
star
32

wirefilter

An execution engine for Wireshark-like filters
Rust
947
star
33

workers-chat-demo

JavaScript
867
star
34

pint

Prometheus rule linter/validator
Go
827
star
35

utahfs

UtahFS is an encrypted storage system that provides a user-friendly FUSE drive backed by cloud storage.
Go
805
star
36

terraform-provider-cloudflare

Cloudflare Terraform Provider
Go
775
star
37

Stout

A reliable static website deploy tool
Go
749
star
38

goflow

The high-scalability sFlow/NetFlow/IPFIX collector used internally at Cloudflare.
Go
729
star
39

unsee

Alert dashboard for Prometheus Alertmanager
Go
710
star
40

mitmengine

A MITM (monster-in-the-middle) detection tool. Used to build MALCOLM:
Go
690
star
41

workers-graphql-server

๐Ÿ”ฅLightning-fast, globally distributed Apollo GraphQL server, deployed at the edge using Cloudflare Workers
JavaScript
635
star
42

cloudflare-php

PHP library for the Cloudflare v4 API
PHP
616
star
43

react-gateway

Render React DOM into a new context (aka "Portal")
JavaScript
569
star
44

xdpcap

tcpdump like XDP packet capture
Go
567
star
45

ahocorasick

A Golang implementation of the Aho-Corasick string matching algorithm
Go
541
star
46

lua-resty-logger-socket

Raw-socket-based Logger Library for Nginx (based on ngx_lua)
Perl
477
star
47

mmap-sync

Rust library for concurrent data access, using memory-mapped files, zero-copy deserialization, and wait-free synchronization.
Rust
453
star
48

pages-action

JavaScript
450
star
49

speedtest

Component to perform network speed tests against Cloudflare's edge network
JavaScript
435
star
50

stpyv8

Python 3 and JavaScript interoperability. Successor To PyV8 (https://github.com/flier/pyv8)
C++
430
star
51

nginx-google-oauth

Lua module to add Google OAuth to nginx
Lua
425
star
52

worker-typescript-template

ส• โ€ขฬุˆโ€ขฬ€) TypeScript template for Cloudflare Workers
TypeScript
424
star
53

gokeyless

Go implementation of the keyless protocol
Go
420
star
54

golibs

Various small golang libraries
Go
402
star
55

sandbox

Simple Linux seccomp rules without writing any code
C
385
star
56

mmproxy

mmproxy, the magical PROXY protocol gateway
C
370
star
57

svg-hush

Make it safe to serve untrusted SVG files
Rust
368
star
58

boring

BoringSSL bindings for the Rust programming language.
Rust
357
star
59

cobweb

COBOL to WebAssembly compiler
COBOL
353
star
60

rustwasm-worker-template

A template for kick starting a Cloudflare Worker project using workers-rs. Write your Cloudflare Worker entirely in Rust!
Rust
350
star
61

workers-types

TypeScript type definitions for authoring Cloudflare Workers.
TypeScript
350
star
62

lua-resty-cookie

Lua library for HTTP cookie manipulations for OpenResty/ngx_lua
Perl
347
star
63

cloudflare-ingress-controller

A Kubernetes ingress controller for Cloudflare's Argo Tunnels
Go
344
star
64

node-cloudflare

Node.js API for Client API
JavaScript
335
star
65

serverless-registry

A Docker registry backed by Workers and R2.
TypeScript
327
star
66

cfweb3

JavaScript
313
star
67

workerskv.gui

(WIP) A cross-platform Desktop application for exploring Workers KV Namespace data
Svelte
306
star
68

JSON.is

Open-source documentation for common JSON formats.
JavaScript
302
star
69

sqlalchemy-clickhouse

Python
299
star
70

cloudflare.github.io

Cloudflare โค๏ธ Open Source
CSS
298
star
71

doom-wasm

Chocolate Doom WebAssembly port with WebSockets support
C
297
star
72

json-schema-tools

Packages for working with JSON Schema and JSON Hyper-Schema
JavaScript
296
star
73

chatgpt-plugin

Build ChatGPT plugins with Cloudflare's Developer Platform ๐Ÿค–
JavaScript
289
star
74

chanfana

OpenAPI 3 and 3.1 schema generator and validator for Hono, itty-router and more!
TypeScript
284
star
75

tls-tris

crypto/tls, now with 100% more 1.3. THE API IS NOT STABLE AND DOCUMENTATION IS NOT GUARANTEED.
Go
283
star
76

gortr

The RPKI-to-Router server used at Cloudflare
Go
283
star
77

react-modal2

๐Ÿ’ญ Simple modal component for React.
JavaScript
279
star
78

isbgpsafeyet.com

Is BGP safe yet?
HTML
278
star
79

keyless

Cloudflare's Keyless SSL Server Reference Implementation
C
272
star
80

pp-browser-extension

Client for Privacy Pass protocol providing unlinkable cryptographic tokens
TypeScript
268
star
81

dog

Durable Object Groups
TypeScript
268
star
82

tubular

BSD socket API on steroids
C
261
star
83

go

Go with Cloudflare experimental patches
Go
260
star
84

cloudflare-rs

Rust library for the Cloudflare v4 API
Rust
256
star
85

cloudflare-typescript

The official Typescript library for the Cloudflare API
TypeScript
251
star
86

puppeteer

Puppeteer Core fork that works with Cloudflare Browser Workers
TypeScript
247
star
87

shellflip

Graceful process restarts in Rust
Rust
245
star
88

kv-asset-handler

Routes requests to KV assets
TypeScript
244
star
89

mod_cloudflare

C
243
star
90

semver_bash

Semantic Versioning in Bash
Shell
238
star
91

cfssl_trust

CFSSL's CA trust store repository
Go
226
star
92

doca

A CLI tool that scaffolds API documentation based on JSON HyperSchemas.
JavaScript
224
star
93

alertmanager2es

Receives HTTP webhook notifications from AlertManager and inserts them into an Elasticsearch index for searching and analysis
Go
218
star
94

pmtud

Path MTU daemon - broadcast lost ICMP packets on ECMP networks
C
218
star
95

origin-ca-issuer

Go
216
star
96

worker-template-router

JavaScript
216
star
97

Cloudflare-WordPress

A Cloudflare plugin for WordPress
PHP
215
star
98

cloudflare-docs-engine

A documentation engine built on Gatsby, powering Cloudflareโ€™s docs https://github.com/cloudflare/cloudflare-docs
JavaScript
215
star
99

python-worker-hello-world

Python hello world for Cloudflare Workers
JavaScript
209
star
100

saffron

The cron parser powering Cron Triggers on Cloudflare Workers
Rust
207
star