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), orpages_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::varsees nothing and there is no.env. CRON_SECRET, if the app haswisp::cron: set it as a secret; the cron triggers send it.WISP_STORE=d1:DBand the rest: Environment variables.
Limits
- No threads, sockets or files: use
wisp::spawnandwisp::sleep, nottokio::spawn. See What works on the edge. - WebSockets work through
WebSocketPair, one connection to one isolate (WebSockets);Response::streamandResponse::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 underwrangler dev) and retires the instance, so a broadcast between connections needs a Durable Object or a realtime service. wisp::everyis not in the edge build.RateLimitcounts in the memory of each isolate, so each isolate has its own count.wisp::channel: the build of an app that calls Wisp'schannelexports aWispRoomDurable Object and binds it asWISP_ROOMinwrangler.toml. The build finds the call as the compiler does:wisp::channel(,use wisp::channel, an alias or a glob. A comment andmpsc::channeldo not count. The build adds the binding and itsnew_sqlite_classesmigrationwisp-room-1after your own migrations. It adds nothing if your config namesWispRoomalready. The build starts from your config each time, so a migration that you add later comes beforewisp-room-1. To put your migration afterwisp-room-1, first copy theWISP_ROOMbinding and thewisp-room-1migration into your config, then add yours after them. Each channel name has its own object (idFromName(name)). A request the app answers withchannel(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 ownsubscribe()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.wasmis over it. The free plan gives a request 10 ms of CPU. - Cron:
wisp::cronbecomes the Worker's cron triggers. Cloudflare counts the weekday 1 (Sunday) to 7, so the build converts it:0 9 * * 1-5becomes0 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:publicwith an[assets]entry; Pages:public, beside_worker.js).- Pages'
_routes.jsonexcludes 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 instatic/keep files off the worker. Table::savedandRestare per-instance memory unlessWISP_STORE=d1:DBis set, with a[[d1_databases]]binding namedDBin 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(..).allandfirstfill 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(orWISP_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),kvandblobsare files under.wisp/data(WISP_KV_<NAME>=memorykeeps them in memory), andsqlreaches D1 withWISP_SQL_<NAME>=d1-http:<account>/<database>.platform::callanswers 501 there: bindings exist only on Cloudflare. See Storage. - Anything else:
wisp::platform::call(binding, method, &[&args...])runsenv[binding][method](...args)and returnsCalled { body, bytes }. Use.json::<T>()for a JSON result; bytes, streams andResponsebodies come back as bytes. It covers Workers AI, Queuessend, Durable Object stubs, Vectorize, Analytics Engine, service bindings andsend_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 ofrequest.cf(city,colo,asn,timezone...) andcx.cf_json()returns all of it. Both areNoneoff Cloudflare, whatever headers the client sends.cx.client_ip()isCF-Connecting-IP.wisp::uuid()iscrypto.randomUUID().wisp::now_ms()isDate.now()(Unix milliseconds;std::time::SystemTime::now()panics in wasm).wisp::hmac_sha256andcx.need_signature("STRIPE_WEBHOOK_SECRET", "stripe-signature")?check webhooks.wisp::passwordhashes passwords.wisp::spawn(async { ... })callsctx.waitUntilwhile the work runs: the instance stays alive until it finishes.
Replace Pages Functions with Wisp
| Pages Functions | Wisp |
|---|---|
functions/api/users/[id].ts, onRequestGet | src/routes/api/users/[id]/+server.rs, fn get(id: u64) |
[[path]].ts catch-all | src/routes/api/[...path]/+server.rs |
functions/_middleware.ts | src/hooks.rs fn before(cx) (all routes), or fn before in a +server.rs |
env.RECIPES.get/put/list | wisp::kv("RECIPES") (above) |
env.BUCKET, env.DB | wisp::blobs("BUCKET"), wisp::sql("DB") |
other bindings (env.AI, queues) | wisp::platform::call |
env.STRIPE_SECRET_KEY | wisp::env("STRIPE_SECRET_KEY") (npx wrangler secret put) |
context.waitUntil(p) | wisp::spawn(async { ... }) |
request.cf.country | cx.cf("country") |
Date.now() | wisp::now_ms() |
crypto.subtle HMAC, randomUUID | wisp::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 scheduled | wisp::cron("0 3 * * *", f) (Workers target) |
Response.redirect, Set-Cookie | wisp::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?