Skip to content
This repository was archived by the owner on Mar 13, 2025. It is now read-only.

Commit 0f3607e

Browse files
mrbbotmrbbot
committed
Initial docs version
1 parent 31ca4e2 commit 0f3607e

25 files changed

+1827
-230
lines changed

‎.prettierrc

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"proseWrap": "always"
3+
}

‎README.md

+58-122
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,68 @@
1-
# 🔥 Miniflare (WIP)
1+
# 🔥 Miniflare
22

3-
Fun, full-featured, fully-local simulator for developing and testing Cloudflare Workers
3+
Fun, full-featured, fully-local simulator for developing and testing Cloudflare
4+
Workers
5+
6+
**See <https://miniflare.dev> for many more details.**
47

58
## Features
69

10+
- 📨 Fetch Events (with HTTP server and manual triggering)
11+
- ⏰ Scheduled Events (with manual and cron triggering)
12+
- 🔑 Variables and Secrets with `.env` Files
13+
- 📚 Modules Support
714
- 📦 KV (with optional persistence)
815
- ✨ Cache (with optional persistence)
916
- 📌 Durable Objects (with optional persistence)
1017
- 🌐 Workers Sites
11-
- 📨 Fetch Events (with HTTP server and manual triggering)
12-
- ⏰ Scheduled Events (with manual and cron triggering)
1318
- ✉️ WebSockets
14-
- 📄 HTMLRewriter
15-
- 🔑 `.env` File Support (for secrets)
16-
- 🕸 Web Standards: Base64, Timers, Fetch, Encoding, URL, Streams, Crypto
17-
- 📚 Modules Support
18-
- 🛠 Custom Builds Support
19+
- 🛠 Custom & Wrangler Builds Support
1920
- ⚙️ WebAssembly Support
2021
- 🗺 Source Map Support
22+
- 🕸 Web Standards: Base64, Timers, Fetch, Encoding, URL, Streams, Crypto
23+
- 📄 HTMLRewriter
2124
- 👀 Automatic Reload on File Changes
2225
- 💪 Written in TypeScript
2326

24-
## CLI Usage
27+
## Install
28+
29+
Miniflare is installed using npm:
30+
31+
```shell
32+
$ npm install -g miniflare # either globally..
33+
$ npm install -D miniflare # ...or as a dev dependency
34+
```
35+
36+
## Using the CLI
37+
38+
```shell
39+
$ miniflare worker.js --watch --debug
40+
[mf:dbg] Options:
41+
[mf:dbg] - Scripts: worker.js
42+
[mf:dbg] Reloading worker.js...
43+
[mf:inf] Worker reloaded!
44+
[mf:dbg] Watching .env, worker.js, wrangler.toml...
45+
[mf:inf] Listening on :8787
46+
[mf:inf] - http://127.0.0.1:8787
47+
```
48+
49+
## Using the API
50+
51+
```js
52+
import { Miniflare } from "miniflare";
53+
54+
const mf = new Miniflare({
55+
script: `
56+
addEventListener("fetch", (event) => {
57+
event.respondWith(new Response("Hello Miniflare!"));
58+
});
59+
`,
60+
});
61+
const res = await mf.dispatchFetch("http://localhost:8787/");
62+
console.log(await res.text()); // Hello Miniflare!
63+
```
64+
65+
## CLI Reference
2566

2667
```
2768
Usage: miniflare [script] [options]
@@ -34,8 +75,8 @@ Options:
3475
-d, --debug Log debug messages [boolean]
3576
-c, --wrangler-config Path to wrangler.toml [string]
3677
--wrangler-env Environment in wrangler.toml to use [string]
37-
-m, --modules Enable ES modules [boolean]
38-
--modules-rule ES modules import rule (TYPE=GLOB) [array]
78+
-m, --modules Enable modules [boolean]
79+
--modules-rule Modules import rule (TYPE=GLOB) [array]
3980
--build-command Command to build project [string]
4081
--build-base-path Working directory for build command [string]
4182
--build-watch-path Directory to watch for rebuilding on changes [string]
@@ -56,115 +97,10 @@ Options:
5697
--wasm WASM module to bind (NAME=PATH) [array]
5798
```
5899

59-
`[script]` should be a path to a pre-bundled Worker.
60-
If you're using Webpack for instance, set this to your output file.
61-
62-
**(Recommended)** Use `--debug`/`-d` to see additional log messages including processed options and watched files.
63-
64-
**(Recommended)** Use `--wrangler-config <toml_path>`/`-c <toml_path>` to load options for KV, cache, etc from a `wrangler.toml` file.
65-
If `[script]` is omitted, Miniflare tries to automatically infer it from the `wrangler.toml` file.
66-
You can also include an additional `[miniflare]` section for Miniflare specific configuration:
67-
68-
```toml
69-
[miniflare]
70-
host = "127.0.0.1" # --host
71-
port = 8787 # --port
72-
upstream = "https://mrbbot.dev" # --upstream
73-
kv_persist = true # --kv-persist
74-
cache_persist = true # --cache-persist
75-
durable_objects_persist = true # --do-persist
76-
env_path = ".env" # --env
77-
wasm_bindings = [ # --wasm
78-
{ name = "MODULE", path="module.wasm" }
79-
]
80-
```
81-
82-
KV and cache persistence can be enabled with the `--kv-persist` and `--cache-persist` flags respectively.
83-
Including these on their own will store KV and Cache data in the `.mf` directory.
84-
Optionally, you can specify a path (e.g. `--kv-persist ./data`) to use a different location.
85-
86-
## Programmatic Usage
87-
88-
```javascript
89-
import { ConsoleLog, Miniflare, Request } from "miniflare";
90-
91-
// Loading script from file
92-
const mf = new Miniflare({
93-
// Some options omitted, see src/options/index.ts for the full list
94-
scriptPath: "./path/to/script.js",
95-
sourceMap: true,
96-
log: new ConsoleLog(), // Defaults to no-op logger
97-
wranglerConfigPath: "wrangler.toml",
98-
watch: true,
99-
port: 8787,
100-
upstream: "https://mrbbot.dev",
101-
crons: ["0 * * * *"],
102-
kvNamespaces: ["TEST_NAMESPACE"],
103-
kvPersist: true,
104-
cachePersist: "./data/",
105-
durableObjects: {
106-
OBJECT: "ObjectClass",
107-
},
108-
sitePath: "./public/",
109-
envPath: ".env",
110-
});
111-
112-
// Loading script from string
113-
const mf = new Miniflare({
114-
script: `
115-
addEventListener("fetch", (event) => {
116-
event.respondWith(handleRequest(event.request));
117-
event.waitUntil(Promise.resolve("Something"));
118-
});
119-
120-
async function handleRequest(request) {
121-
const value = await TEST_NAMESPACE.get("key");
122-
return new Response(\`Hello from Miniflare! key="\${value}"\`, {
123-
headers: { "content-type": "text/plain" },
124-
})
125-
}
126-
127-
addEventListener("scheduled", (event) => {
128-
event.waitUntil(Promise.resolve("Something else"));
129-
});
130-
`,
131-
kvNamespaces: ["TEST_NAMESPACE"],
132-
log: new ConsoleLog(),
133-
});
134-
135-
// Manipulate KV outside of worker (useful for testing)
136-
const TEST_NAMESPACE = await mf.getKVNamespace("TEST_NAMESPACE");
137-
await TEST_NAMESPACE.put("key", "testing");
138-
139-
// Manipulate cache outside of worker
140-
const cache = await mf.getCache();
141-
const cachedRes = await cache.match(new Request("http://localhost"));
142-
143-
// Manipulate Durable Objects outside of worker
144-
const OBJECT = await mf.getDurableObjectNamespace("OBJECT");
145-
const stub = OBJECT.get(OBJECT.idFromName("name"));
146-
const doRes = await stub.fetch("http://localhost");
147-
const storage = await stub.storage(); // Extra Miniflare-only API
148-
await storage.put("key", new Set(["testing"]));
149-
150-
// Dispatch fetch events and get body
151-
const res = await mf.dispatchFetch("http://localhost", { method: "POST" });
152-
const res = await mf.dispatchFetch(new Request("http://localhost"));
153-
154-
const body = await res.text();
155-
console.log(body); // Hello from Miniflare! key="testing"
156-
157-
const waitUntil = await res.waitUntil();
158-
console.log(waitUntil[0]); // Something
159-
160-
// Start HTTP server
161-
mf.createServer().listen(3000);
162-
163-
// Dispatch scheduled event at specific time
164-
const waitUntil2 = await mf.dispatchScheduled(Date.now());
165-
console.log(waitUntil2[0]); // Something else
166-
```
167-
168100
## Acknowledgements
169101

170-
Many thanks to [dollarshaveclub/cloudworker](https://github.com/dollarshaveclub/cloudworker) and [gja/cloudflare-worker-local](https://github.com/gja/cloudflare-worker-local) for inspiration.
102+
Many thanks to
103+
[dollarshaveclub/cloudworker](https://github.com/dollarshaveclub/cloudworker)
104+
and
105+
[gja/cloudflare-worker-local](https://github.com/gja/cloudflare-worker-local)
106+
for inspiration.

‎docs/.vitepress/config.js

+41-2
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,50 @@
11
module.exports = {
2-
title: "🔥 Miniflare",
2+
title: "Miniflare",
33
description:
44
"Fun, full-featured, fully-local simulator for Cloudflare Workers",
55
themeConfig: {
66
repo: "mrbbot/miniflare",
77
docsDir: "docs",
88
editLinks: true,
9-
nav: [{ text: "Guide", link: "/guide/" }],
9+
sidebar: [
10+
{
11+
text: "Getting Started",
12+
children: [
13+
{ text: "🔥 Miniflare", link: "/" },
14+
{ text: "💻 Using the CLI", link: "/cli.html" },
15+
{ text: "🧰 Using the API", link: "/api.html" },
16+
// { text: "🚧 Changelog", link: "/changelog.html" },
17+
],
18+
},
19+
{
20+
text: "Guide",
21+
children: [
22+
{ text: "📨 Fetch Events", link: "/fetch.html" },
23+
{ text: "⏰ Scheduled Events", link: "/scheduled.html" },
24+
{ text: "🔑 Variables and Secrets", link: "/variables-secrets.html" },
25+
{ text: "📚 Modules", link: "/modules.html" },
26+
{ text: "📦 KV", link: "/kv.html" },
27+
{ text: "✨ Cache", link: "/cache.html" },
28+
{ text: "📌 Durable Objects", link: "/durable-objects.html" },
29+
{ text: "🌐 Workers Sites", link: "/sites.html" },
30+
{ text: "✉️ WebSockets", link: "/web-sockets.html" },
31+
{ text: "🛠 Builds", link: "/builds.html" },
32+
{ text: "⚙️ WebAssembly", link: "/web-assembly.html" },
33+
{ text: "🗺 Source Maps", link: "/source-maps.html" },
34+
{ text: "🕸 Web Standards", link: "/standards.html" },
35+
{ text: "📄 HTMLRewriter", link: "/html-rewriter.html" },
36+
],
37+
},
38+
{
39+
text: "Recipes",
40+
children: [
41+
{
42+
text: "⚡️ Developing with esbuild",
43+
link: "/recipes/esbuild.html",
44+
},
45+
{ text: "✅ Testing with AVA", link: "/recipes/ava.html" },
46+
],
47+
},
48+
],
1049
},
1150
};

0 commit comments

Comments
 (0)