Wisp is in pre-release, self-hosted since GitHub suspended us. Install it, or see the changelog.

Wisp

Host on Cloudflare

Cloudflare runs the app as WebAssembly on its edge, as a Worker (cloudflare) or on Pages (pages).

Build

rustup target add wasm32-unknown-unknown     # once
wisp build --target cloudflare               # Workers: dist/cloudflare
wisp build --target pages                    # Pages: dist/pages

--out <folder> changes the folder. No wasm-bindgen or other tool is needed. In Cloudflare's CI a plain wisp build picks the target from WORKERS_CI (Workers: cloudflare) or CF_PAGES (Pages: pages).

A rebuild removes from the folder what the last build wrote and this one did not (a file deleted from static/), listed in its .wisp-files; what else is there (.wrangler/ state of wrangler dev) stays.

Your wrangler config

The app's own wrangler.jsonc, wrangler.json or wrangler.toml at its root is where its bindings (D1, KV, R2, services), vars, [env.*], observability and placement go. The build copies it into its folder and sets only Wisp's keys:

  • main = "worker.js" (Workers, also in each [env.*] that sets its own), or pages_build_output_dir = "public" (Pages);
  • [assets] directory = "public" (Workers, when there are static files; the table's other keys stay);
  • the app's cron triggers, added to yours;
  • name (the package's), compatibility_date (2025-09-01) and [observability] enabled = true (Workers Logs) only where you set none.

Everything else is kept as you wrote it. A JSONC config is written as wrangler.json (its comments left out). Paths in it are read from the folder, so give migrations_dir and the like from there, or run wrangler d1 migrations from the app's root. Without a config of your own the build writes Wisp's alone. wisp deploy init cloudflare (or cloudflare-pages) writes you a wrangler.toml to start from when there is none.

Deploy

Workers, from dist/cloudflare:

npx wrangler deploy
npx wrangler secret put WISP_SECRET

Pages, from dist/pages (its wrangler.toml names public, which holds _worker.js, _routes.json, app.wasm and the static files):

npx wrangler pages deploy

wisp deploy init cloudflare and wisp deploy init cloudflare-pages write a GitHub Actions workflow that builds and deploys on push to main; they read the secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID.

Cloudflare's own build

Workers Builds runs npx wrangler deploy at the repository's root after the build command, and Pages' Git builds read the root config. So in Cloudflare's CI (WORKERS_CI, CF_PAGES) the build also writes the merged config at the app's root, its paths into the folder (main = "dist/cloudflare/worker.js", pages_build_output_dir = "dist/pages/public"): set the build command to wisp build and keep the default deploy command. That build image needs Rust and wisp: install them in the build command (curl https://sh.rustup.rs -sSf | sh -s -- -y && rustup target add wasm32-unknown-unknown && cargo install --git https://wisp.ar0.eu/ wisp-web && wisp build), or build in GitHub Actions with wisp deploy init.

Environment

  • WISP_SECRET: a Worker secret (above), or on Pages under Settings.
  • Read other values with wisp::env("KEY"); std::env::var sees nothing and there is no .env.
  • CRON_SECRET, if the app has wisp::cron: set it as a secret; the cron triggers send it.
  • WISP_STORE=d1:DB and the rest: Environment variables.

Limits

  • No threads, sockets or files: use wisp::spawn and wisp::sleep, not tokio::spawn. See What works on the edge.
  • WebSockets work through WebSocketPair, one connection to one isolate (WebSockets); Response::stream and Response::events (SSE) are live. A socket belongs to the request that opened it: sending to another connection's socket fails on Workers ("Cannot perform I/O on behalf of a different request", checked under wrangler dev) and retires the instance, so a broadcast between connections needs a Durable Object or a realtime service.
  • wisp::every is not in the edge build. RateLimit counts in the memory of each isolate, so each isolate has its own count.
  • wisp::channel: the build of an app that calls Wisp's channel exports a WispRoom Durable Object and binds it as WISP_ROOM in wrangler.toml. The build finds the call as the compiler does: wisp::channel(, use wisp::channel, an alias or a glob. A comment and mpsc::channel do not count. The build adds the binding and its new_sqlite_classes migration wisp-room-1 after your own migrations. It adds nothing if your config names WispRoom already. The build starts from your config each time, so a migration that you add later comes before wisp-room-1. To put your migration after wisp-room-1, first copy the WISP_ROOM binding and the wisp-room-1 migration into your config, then add yours after them. Each channel name has its own object (idFromName(name)). A request the app answers with channel(name).websocket() or .events() (after its hooks and guards) goes to that object. The object holds the sockets with the hibernation API, so it sleeps between messages. Wisp posts a send from any other request there. Every other WebSocket and event stream stays in the isolate, with no extra hop. Your own subscribe() loops see only their isolate's sends. The object drops the event stream of a client that does not read it, at the first send that finds more than 256 sends waiting for it. The drop discards the sends that wait, and the client can connect again. The count is sends, not bytes. Workers only: Pages has no Durable Objects. Wisp logs a failed send once for each socket.
  • Started timers and fetches keep the instance alive (waitUntil).
  • A Worker is at most 64 MiB uncompressed (every plan); the build warns when app.wasm is over it. The free plan gives a request 10 ms of CPU.
  • Cron: wisp::cron becomes the Worker's cron triggers. Cloudflare counts the weekday 1 (Sunday) to 7, so the build converts it: 0 9 * * 1-5 becomes 0 9 * * 2,3,4,5,6. Two schedules that convert to one trigger run from it together.

Cron on Pages

Pages runs no cron triggers. For an app with wisp::cron or wisp::work the Pages build writes cron/: a small Worker whose triggers are the app's schedules, each asking the site for /_wisp/cron/<schedule> with CRON_SECRET. Its wrangler.toml takes the site's address from SITE_URL at build time (set it, or edit [vars] SITE_URL). Deploy it once beside the site:

cd dist/pages/cron
npx wrangler deploy
npx wrangler secret put CRON_SECRET     # the same as the Pages project's

Files and Data

  • static/ goes into the build output and is served by Cloudflare before the app runs (Workers: public with an [assets] entry; Pages: public, beside _worker.js).
  • Pages' _routes.json excludes the static files from the worker. It takes 100 rules (one is the include) of 100 characters at most: folders go in first, and files with no room reach the worker, which then answers a GET the app answers 404 from Pages' files (env.ASSETS). The build warns when that happens; a few folders in static/ keep files off the worker.
  • Table::saved and Rest are per-instance memory unless WISP_STORE=d1:DB is set, with a [[d1_databases]] binding named DB in your wrangler config. See Saved tables.

Bindings: KV, R2, D1 and the Rest

Bindings declared in wrangler.toml ([[kv_namespaces]], [[r2_buckets]], [[d1_databases]], [ai]...) are reached by name. The calls are async and return wisp::Result. An app that never calls them carries none of this code.

let kv = wisp::kv("RECIPES");
kv.put_for(&format!("sess:{hash}"), &session, 30 * 86_400).await?; // expirationTtl
let raw: Option<String> = kv.get("user:1").await?;
let user: Option<User> = kv.get_json("user:1").await?;    // #[derive(FromJson)]
kv.put_json("user:1", &user).await?;
let page = kv.list("sess:").await?;                        // Page { keys, cursor }
let next = kv.list_page("sess:", page.cursor.as_deref().unwrap_or(""), 1000).await?;
kv.delete("user:1").await?;

// Metadata, absolute expiry, binding-only options (`cacheTtl`):
use wisp::platform::KvPut;
kv.put_with("k", "v", KvPut { ttl: Some(600), meta: Some(r#"{"v":2}"#.into()), ..Default::default() }).await?;
let entry = kv.get_with_meta("k").await?;                  // KvEntry { value, meta }

let photos = wisp::blobs("PHOTOS");                        // R2
photos.put("a.png", png, "image/png").await?;
let blob = photos.get("a.png").await?;                     // Blob { body, content_type }

let rows: Vec<Recipe> = wisp::sql("DB").all("select * from recipes where owner = ?", &[&id]).await?; // D1
let changed = wisp::sql("DB").run("delete from recipes where id = ?", &[&id]).await?;

A page of list (up to 1000 keys) or list_page (up to limit) can hold fewer keys while more exist. Walk until the cursor is None.

  • sql(..).all and first fill a #[json(skip)] field of the row type from the column of its name. They do not run the #[validate] rules of the type.
  • The store is the binding of the same name. WISP_KV_<NAME>=cf:BINDING (or WISP_BLOB_<NAME>) points a name at another binding. The same code runs on every other host with that host's driver: see Storage.
  • A missing binding answers a 500 that names it ("there is no binding RECIPES. Add it to wrangler.toml"). It never panics.
  • Off the edge (wisp dev, the built-in server), kv and blobs are files under .wisp/data (WISP_KV_<NAME>=memory keeps them in memory), and sql reaches D1 with WISP_SQL_<NAME>=d1-http:<account>/<database>. platform::call answers 501 there: bindings exist only on Cloudflare. See Storage.
  • Anything else: wisp::platform::call(binding, method, &[&args...]) runs env[binding][method](...args) and returns Called { body, bytes }. Use .json::<T>() for a JSON result; bytes, streams and Response bodies come back as bytes. It covers Workers AI, Queues send, Durable Object stubs, Vectorize, Analytics Engine, service bindings and send_email.
let out = wisp::platform::call("AI", "run", &[&"@cf/meta/llama-3.1-8b-instruct", &prompt]).await?;
let answer: wisp::Value = out.json()?;
  • cx.cf("country") reads one field of request.cf (city, colo, asn, timezone...) and cx.cf_json() returns all of it. Both are None off Cloudflare, whatever headers the client sends. cx.client_ip() is CF-Connecting-IP.
  • wisp::uuid() is crypto.randomUUID(). wisp::now_ms() is Date.now() (Unix milliseconds; std::time::SystemTime::now() panics in wasm). wisp::hmac_sha256 and cx.need_signature("STRIPE_WEBHOOK_SECRET", "stripe-signature")? check webhooks. wisp::password hashes passwords.
  • wisp::spawn(async { ... }) calls ctx.waitUntil while the work runs: the instance stays alive until it finishes.

Replace Pages Functions with Wisp

Pages FunctionsWisp
functions/api/users/[id].ts, onRequestGetsrc/routes/api/users/[id]/+server.rs, fn get(id: u64)
[[path]].ts catch-allsrc/routes/api/[...path]/+server.rs
functions/_middleware.tssrc/hooks.rs fn before(cx) (all routes), or fn before in a +server.rs
env.RECIPES.get/put/listwisp::kv("RECIPES") (above)
env.BUCKET, env.DBwisp::blobs("BUCKET"), wisp::sql("DB")
other bindings (env.AI, queues)wisp::platform::call
env.STRIPE_SECRET_KEYwisp::env("STRIPE_SECRET_KEY") (npx wrangler secret put)
context.waitUntil(p)wisp::spawn(async { ... })
request.cf.countrycx.cf("country")
Date.now()wisp::now_ms()
crypto.subtle HMAC, randomUUIDwisp::hmac_sha256, cx.need_signature, wisp::uuid()
fetch(url)wisp::fetch(req).await? (the same call as on a server; in the edge build it is the host's fetch)
cron Worker scheduledwisp::cron("0 3 * * *", f) (Workers target)
Response.redirect, Set-Cookiewisp::redirect, cx.set_cookie

Build with wisp build --target pages and deploy dist/pages. Each binding keeps its name in the Pages settings or wrangler.toml.

A streamed reply (a model's server-sent events) is wisp::fetch_stream(req).await?, then Response::stream (or .respond()) passes its pieces on as they arrive.

A static site with one API route keeps its pages on the CDN: build the site with wisp build --static into dist/, the API as a small Wisp app of its own with wisp build --target pages, copy that app's public/_worker.js and public/app.wasm into dist/, and write dist/_routes.json as {"version":1,"include":["/api/*"],"exclude":[]} so only /api/* reaches the worker. This site's Ask Wisp chat (POST /api/chat) is built that way (ask/ and tools/site.sh in the wisp-docs repo).

More

Edge and serverless targets, Deploying.

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.