Edge and Serverless Targets
rustup target add wasm32-unknown-unknown # once
wisp build --target cloudflare # dist/cloudflare (--out <folder>)
The app compiles to WebAssembly in a folder with the host's config, an entry file and the static files. No other tool is needed.
| Target | For | From dist/<target> |
|---|---|---|
cloudflare | Workers | npx wrangler deploy (secrets: npx wrangler secret put WISP_SECRET) |
pages | Cloudflare Pages | npx wrangler pages deploy in dist/pages (WISP_SECRET under Settings) |
deno | Deno Deploy | deno deploy --app <name> --prod (local: deno run -A main.ts) |
vercel | Vercel | npx vercel deploy --prebuilt (env var WISP_SECRET) |
netlify | Netlify | npx netlify deploy --prod |
node | Amplify, Firebase, Azure, Stormkit, Zeabur, any Node host | npm start |
bun | Bun (Bun.listen) | bun server.mjs |
lambda | AWS Lambda | below |
Other hosts (each has a page under Hosting):
| Host | Use |
|---|---|
| Amplify, Firebase, Azure Static Web Apps, Stormkit, Zeabur | --target node (npm start). hosts/*.md in the output has each host's glue (Azure) |
| GitHub Pages, GitLab Pages | --static, publish dist/; a project site under /repo sets base = "/repo" |
| Fly.io | wisp deploy init docker, fly launch, fly deploy, fly secrets set WISP_SECRET=... |
| Railway, Render | wisp deploy init docker, point at the repo, set WISP_SECRET |
| Cloud Run | wisp deploy init docker, gcloud run deploy --source . |
A kept CACHE_PUBLIC page sends cache-control: public, s-maxage=<CACHE>, stale-while-revalidate=<CACHE_STALE>, so a CDN in front of any target can keep it. No such header when the app has a before or after hook, or when the page or its layouts have a guard (SIGNED_IN, MIDDLEWARE, RATE_LIMIT, CORS). The same holds when a +server.rs has a before function or a guard. Those run on each request and a CDN skips them. Set your own cache-control then. There is also no such header when the answer depends on accept: a page that shares its path with an endpoint, or a #[derive(Rest)] list. A CDN that skips vary can send one answer to the wrong client. A plain CACHE page sends none. A stale reply keeps s-maxage=<CACHE>, so a CDN can keep a page up to 2 × (CACHE + CACHE_STALE) after its render. A PPR page (a shell with holes) gets no such header: its holes are per request. Native and edge builds send the same header.
To serve the built /_app/ files from a CDN, set WISP_ASSET_BASE at build (WISP_ASSET_BASE=https://cdn.example.com).
Static Export
Compiled modules are served as .js everywhere: src/lib/x.ts is /_app/c/lib/x.js, since static hosts type .ts as video/mp2t. A src/lib holding both x.js and x.ts is a build error.
The export lists what it wrote in .wisp/export-*.list. The next export into the same folder deletes the listed files that it did not write again. Your own files are safe. The export fails with the export refuses to write "<path>": the path has a control character for a path with a control character (a line break, for example). It also refuses a path through a symlink or junction in the out folder: the export refuses to write "<path>": <folder> is a symlink or junction. It follows NPM modules (.mjs) to their imports.
wisp build --static follows <a href>, <link href> (not resource hints) and <img src>, so a [slug] route with no entries is found by a link. A link answering 400 or more, or a link with #id to a written page that has no such id or <a name>, fails the export after the site is written (error /page links to /x, which answered 404, error /page links to /x#intro, but no element has the id intro, N dead links. Fix them, or build with --allow-dead-links to only warn). At most 10000 pages are written. --allow-dead-links (or WISP_DEAD_LINKS=warn) only warns. --no-crawl follows no link. The crawl sends a GET to each page it follows, so a GET route that changes data runs at build time. The emitted _headers CSP relies on hashes and 'self', since a static site has no per-request nonces.
Direct loads with --spa
A route the browser draws (SSR = false, no entries) has no file in the export, so the host must answer its address with index.html. wisp build --spa writes the rules for the common hosts, one per such route. /r/[id] is /r/:id. A rest parameter, or an optional one at the end, gives /files/* and /files. An optional one before other segments gives a rule without it and one with it, so /[[lang]]/blog/[slug] is /blog/:slug and /:lang/blog/:slug. Route groups are not included.
_redirectsfor Netlify and Cloudflare Pages:/r/:id / 200. It names/, not/index.html, because Cloudflare Pages would answer the latter with a cached 308. Yourstatic/_redirectsstays first.vercel.jsonfor Vercel, arewritesentry per route (/r/:id,/files/:rest*). Yourstatic/vercel.jsonkeeps its rewrites first and gets the missing ones.404.html, a copy ofindex.html, for GitHub Pages.
An app with no such route gets none of these.
Browser Extension
wisp build --target extension [--out dist] writes a Chrome extension folder (Manifest V3). It runs the static export of an app that it builds with WISP_EXTENSION=1. wisp new --template extension and examples/extension give a popup with a $state counter, an options page and a background service worker.
You write manifest.json in the app folder. Wisp does not create it. The build copies it to the output and checks it:
manifest_versionmust be 3.- Each path at these keys must be a file of the output:
action.default_popup,options_page,options_ui.page,side_panel.default_path,background.service_worker,background.scripts, and thejsandcssof eachcontent_scriptsentry. A page path can end with a query or a fragment. - A route
/popupgives the filepopup/index.html, so the manifest namespopup/index.html.
Firefox uses background.scripts. The build checks its paths, but no run in Firefox checked the folder. Firefox may load it.
The output differs from --static in these ways:
- Wisp's own files are under
/wisp/, not/_app/. Chrome refuses a file or folder name that starts with_. Where these docs name/_app/, the extension target uses/wisp/. - Each
<a href>to a page that the export wrote names the file of the page./optionsand/options/become/options/index.html, and/becomes/index.html. A query and a fragment stay. Chrome does not open a folder URL as itsindex.html. - The build writes no
_headers,.nojekyllor404.html.
goto() gets no such change. In the extension, goto('/options') fails and Chrome shows "Your file couldn't be accessed". goto('/options/index.html') works.
The CSP of Manifest V3 blocks inline code. So a page of the folder can have no inline script, no on* attribute and no javascript: URL. The build reads each .html and .htm file of the output, also the files that it copies from static/. It finds these items:
- a
<script>with nosrcand with text, when its type is JavaScript,module,importmaporspeculationrules. A data block such astype="application/json"stays. - an attribute whose name starts with
on, such asonclick. - a
javascript:URL in anhref,src,actionorformaction. The check does not decode character references in a value. - these items in the content of a
<template>, because a script can clone it into the page.
Put the code in a .js file under static/ and load it with <script src>.
These fail the build:
| Cause | Error |
|---|---|
no manifest.json in the app folder | manifest.json: an extension build needs a manifest.json in the app folder. |
a base path (base, WISP_BASE) | An extension build takes no base path (base, WISP_BASE). |
an asset base (assets, WISP_ASSET_BASE) | An extension build takes no asset base (assets, WISP_ASSET_BASE). |
a route under /wisp | src/routes/wisp/a: the route /wisp/a is under /wisp, where an extension build writes its own files. Choose another name. |
a static/wisp or static/manifest.json | <path>/static/wisp: an extension build writes /wisp itself. Choose another name. (or /manifest.json) |
| a route with actions, endpoints or a guard | error /x has actions, so it needs a server. An extension has no server for each, then 1 route needs a server. Delete the actions, endpoints and guards, or build with --static |
a file or folder name that starts with _, except _locales at the root | <path>: Chrome refuses a file or folder name that starts with _ (only _locales at the root). Choose another name. |
another manifest_version | manifest.json: manifest_version is 2. Wisp builds Manifest V3: set it to 3. or manifest.json: manifest_version is missing. Set it to 3. |
| a path with no file | manifest.json: action.default_popup is popup, and the output has no file popup |
| a path that is not a string | manifest.json: options_page must be a path, not 5 |
| an inline script | x.html: a <script> with no src. Manifest V3 runs only the code of script files |
an on* attribute | popup/index.html: the attribute onclick on <button>. Manifest V3 runs only the code of script files |
a javascript: URL | x.html: a javascript: URL in the attribute href on <a>. Manifest V3 runs only the code of script files |
| inline code, last line | 4 inline scripts, event handlers or javascript: URLs in the pages. Move the code to a .js file under static/ |
With SITE_URL set, the endpoints of /sitemap.xml, /robots.txt and /feed.xml do not fail the build. The export writes them as files. The build checks the app before the release build, and the routes before the export writes a file. It checks the manifest, the names and the inline code after the export and the copy of static/. The build puts manifest.json on the export list, so the next export into the same --out deletes it before it writes.
The target is for wisp build only. wisp dev serves Wisp's files at /_app/, as for the other targets.
The gate step extension loads the folder in Chrome for Testing 127.0.6533.88 with the DevTools command Extensions.loadUnpacked. It checks the popup counter, chrome.storage, the links, goto('/options/index.html'), that goto('/options') opens the Chrome error page, and that the CSP blocked nothing. Not checked: branded Chrome, Edge, Chromium 153, Firefox and Safari.
Edge Runtime per Route
Vercel and Netlify Edge: add --edge (--target vercel --edge, --target netlify --edge). The wasm app runs as a module (opt-level = "s", for their size limits), and Netlify skips static/ via excludedPath.
Per route, a +page.rs or +server.rs can opt in; the rest stay on the Node function.
const RUNTIME: wisp::Runtime = wisp::Runtime::Edge; // default: Node
- With any Edge route, the build writes both functions from the one app and routes each pattern to its own.
- It must be a literal, and a layout cannot set it.
--edgeputs every route there. - The pattern of an Edge route is wider than the route: a matcher (
[id=int]) does not count, and a parameter takes any segment. The build sends a Node route to the Node function first in two cases. In the first, the route wins over an Edge pattern that it overlaps (item/newbeside the Edge routeitem/[id]). In the second, that Edge pattern has a matcher (item/[slug]besideitem/[id=int]). A Node route with a matcher counts too. - On Vercel, the rules of both kinds follow the route priority, and an Edge pattern ranks without its matcher. So a Node route that ranks below an Edge pattern with a matcher leaves the paths of that pattern on the edge. For example, with the Node route
[...rest]beside the Edge routeitem/[id=int],/item/abcstays on the edge. - On Netlify, the Node route is an excluded path of the edge function. A Node route that overlaps an Edge route with a matcher gets an excluded path too (
/*for[...rest]). So that Edge route never runs on the edge. The same holds for an Edge static route that the Node route hides. Netlify has no rule order. So an excluded path also takes the Edge route that wins over that Node route (a/bbeside the Node routea/[x]). The build warns for each such Edge route, and the Node function serves it. - A host build (
wisp build --target <host>) also writes thegooglefonts and the Open Graph cards ofwisp::og(.., "auto"), as a binary build does. - The build stops, naming the route, if an Edge route uses what WebAssembly lacks (
std::fs,std::thread,std::process, sockets, websockets).
Every WebAssembly build warns, with file:line, for code that cannot run there: std::fs, tokio::fs, std::thread, std::process, sockets (TcpListener, TcpStream, UdpSocket), tokio::spawn (use wisp::spawn), tokio::time (use wisp::sleep), reqwest (use wisp::edge::fetch), and .websocket( on Vercel and Netlify. That code answers 500 when reached.
Servers on Node, Bun and Local Deno
They read raw sockets and the app's HTTP/1.1 parser answers (pipelining, keep-alive, chunked bodies, 413, 431, each route's BODY_LIMIT, the native deadlines with 408). A raw socket quiet for WISP_KEEP_ALIVE_TIMEOUT seconds (65 by default) is closed.
- At startup, a loopback request must get the answer the app gives on a connection in memory (twice, on one connection; a 400 that the app does not itself give fails). If not, or with
WISP_NODE_HTTP=1, they serve withnode:http,Bun.serveorDeno.serve(one stderr line says which). Deno Deploy always usesDeno.serve. - Only the
node:httppath caps a body atWISP_BODY_LIMIT(default 1 MB, then 413). The bridges that read with the host's ownfetch(Workers, Deno, Netlify, Vercel Edge, Bun) stop one byte past the route's limit and the app answers 413. - On Workers, Deno and Netlify, through the fetch handler (
serve), the bridge reads no body of a GET or HEAD request, so the app gets none. The native server gives a GET body tocx.body(). - Through the fetch handler (
serve), a pure route answers in one call. A route can be pure when its+server.rshas a syncfn get()with noCx, no input and no path param. It is pure when no hook, guard,CACHE,COMPRESS,CORSorTIMEOUTis on it. A GET with no query can get a 200 with only a staticcontent-type. Then the bridge keeps the path and host. Later GETs of them run the handler with no request bytes and noCx. Any other result goes the whole way with that result, so the handler runs once per request. Other results are another status, a header, an error, a stream or changes not yet saved. Raw sockets do not use it. - Node's
node:httphandler (WISP_NODE_HTTP=1, Vercel's Node function, Firebase) uses pure routes too. The first GET of a path goes as a lazy request, as through the fetch handler. Only a GET with no query, no body header, onehostthat is not empty and each header name once uses this path. Each value must be Latin-1 with no control byte but a tab. All other requests go whole, as before. - On SIGTERM (not on Windows under Deno) or Ctrl+C, the server stops accepting, lets requests under way finish and exits within 8 s. A second signal exits at once.
AWS Lambda
Run rustup target add x86_64-unknown-linux-musl once. --target lambda writes dist/lambda/bootstrap.zip, the app's static binary, deflated (no C toolchain, unless the app has WebSocket routes). The same bootstrap also runs as a plain server (PORT) on any x86_64 Linux when AWS_LAMBDA_RUNTIME_API is unset, so it is the static musl build for a scratch container or an old distro. musl costs some speed. aarch64 builds are not made yet. Create the function once (runtime provided.al2023, x86_64, handler bootstrap) and add a Function URL (or API Gateway/ALB):
aws lambda create-function --function-name my-app --runtime provided.al2023 --architectures x86_64 \
--handler bootstrap --role <role-arn> --zip-file fileb://dist/lambda/bootstrap.zip
aws lambda update-function-code --function-name my-app --zip-file fileb://dist/lambda/bootstrap.zip
- The binary answers Lambda's runtime API when
AWS_LAMBDA_RUNTIME_APIis set. A plain release build leaves that out.WISP_LAMBDA=1for a plaincargo build --releasekeeps it. - Lambda freezes the process between invocations, so
everyandspawnrun only while one is answered.wisp::cronandwisp::workrun from EventBridge Scheduler schedules in the build'seventbridge.sh(Cron). - A stream is sent whole, cut at 25 s or 4 MB. With a
RESPONSE_STREAMFunction URL andWISP_LAMBDA_STREAM=1it streams (Streaming). A reply over 6 MB gets a 500 with the reason. - WebSockets need an API Gateway WebSocket API (setup) on a single-instance function; a Function URL answers 501.
- Saved tables go in
/tmp, per instance. Usewisp::storefor lasting data. - The
towerfeature withlambda_httpalso works (Testing and mixing with Rust code).
What Works on the Edge
No threads, sockets or files.
| Topic | Rule |
|---|---|
| Tasks and timers | Use wisp::spawn and wisp::sleep. tokio::spawn, tokio::time, sqlx, reqwest and Response::file_in answer 500 there. All work in the binary, Docker, Lambda. |
| Host storage | wisp::kv, wisp::blobs, wisp::sql and wisp::platform::call reach Cloudflare's KV, R2, D1 and any other binding by name. cx.cf(field) reads request.cf. Other hosts use Deno KV, Netlify Blobs, Upstash, S3 or Vercel Blob. call is 501 off Cloudflare. See Storage and Bindings. |
| Secrets | Host secrets. Read them with wisp::env("KEY") (std::env::var sees nothing, and there is no .env). |
| Streaming | Response::stream and Response::events are live on Cloudflare, Deno, Netlify, Vercel, Node. A client that leaves fails send. |
| WebSockets | See below. 501 on Vercel, Netlify and tower: use SSE. |
| Not in the edge build | wisp::every (it does not compile): use the host's queues and cron. RateLimit compiles, but each instance counts its own requests: for one count for the whole site, use the host's rate limiting. wisp::untoken_once and <form guard> need memory between requests and are refused with a 501. |
| Panics | A panic fails only that request (500). |
WebSockets
The same code works on every host that can hold a socket; the rest answer 501, and wisp build --target <host> and wisp check --target <host> warn, naming each route. examples/websocket is an echo that runs on all of them.
| Host | WebSockets |
|---|---|
binary, Docker, node, bun, deno, cloudflare, pages | yes |
lambda | yes, behind an API Gateway WebSocket API |
vercel | 501 and a build warning (waits on a deploy test, Host on Vercel) |
netlify | 501 and a build warning (its functions take no upgrade) |
tower | 501 (upgrade in the host framework) |
- On raw sockets the codec is the native server's (
WISP_WS_IDLE, theBODY_LIMITmessage limit, and a message sent in pieces closed with 1008 unless it makes progress every 10 s and 1 KB/s after that). Where the host frames messages (Bun.serve,Deno.serve, Deploy, Workers) it keeps its own idle time. Wisp still closes with 1009 past the limit (4009 on Deno). - A connection lives in one instance (on Cloudflare, one isolate). Shared state needs a Durable Object of your own or
WISP_STORE.
Where there are no WebSockets
Most live pages only need the server to push. Server-sent events work on every host, and the browser sends with a plain fetch POST. wisp::channel reaches every instance on Cloudflare (a WispRoom Durable Object, bound as WISP_ROOM in wrangler.toml) and Deno (BroadcastChannel, and deno run needs --unstable-broadcast-channel). Elsewhere each instance has its own subscribers, so broadcast through a store or a realtime service.
// src/routes/chat/+server.rs
fn get() -> Response {
wisp::channel("chat").events() // each message, as it is sent
}
fn post(cx: &mut Cx) -> Response {
wisp::channel("chat").send(String::from_utf8_lossy(cx.body()).into_owned());
Response::empty(204)
}
Saved Tables
Rest and Table::saved are per-instance memory unless WISP_STORE is set (no app code):
WISP_STORE | Store |
|---|---|
d1:DB | Cloudflare D1 binding DB |
deno-kv | Deno KV (deno-kv:<path> file or URL) |
libsql://name.turso.io | Turso or any libSQL server over HTTP, with WISP_STORE_TOKEN |
- Each instance reads every row at start.
- A request's changes are one batch before the answer. A failed batch answers 500 and the next request gets a fresh instance.
Jobs
wisp::cron and wisp::work are the same code on every host. wisp build reads each wisp::cron("0 3 * * *", ..) in src/ (the schedule must be a string literal) and writes the host's trigger:
| Host | Trigger |
|---|---|
| Cloudflare | [triggers] crons in wrangler.toml, with the weekday counted 1 to 7 from Sunday |
| Vercel | crons in config.json, with the weekday 0 to 6 (Hobby plan: daily only) |
| Netlify | a scheduled function |
| Cloudflare Pages | a companion Worker in cron/ (Cron on Pages) |
| Deno | a Deno.cron in main.ts |
- A trigger asks the app for
/_wisp/cron/<schedule>withAuthorization: Bearer $CRON_SECRET. Set it as a host secret, or the address is 404. - Cloudflare counts the weekday 1 (Sunday) to 7, Vercel 0 (Sunday) to 6, and Wisp 0 or 7 for Sunday. The build converts the weekday for each host, so
0 9 * * 1-5runs Monday to Friday on all of them. The Cloudflare Worker maps its trigger back to the schedule. Vercel takes a day of the month or of the week, not both: the build stops with an error for a schedule that has both.wisp::crontakes noL,Wor#in the day of the month or the weekday. The build stops with an error for them on Cloudflare, Pages, Vercel, Deno and Lambda (EventBridge). - That runs the schedule's tasks, then every queue's due jobs (an app with
workgets a trigger each minute). Queued jobs needWISP_STORE. - Node, Bun, Lambda, Azure Static Web Apps and Netlify
--edgehave no trigger to write; the build says so and stops. Run the binary or Docker there.
Outbound HTTP
let mut req = wisp::Request::new("POST", "https://api.example.com/rows");
req.header(
"authorization",
&format!("Bearer {}", wisp::env("API_KEY").unwrap_or_default()),
);
req.body = json.into_bytes();
let reply = wisp::edge::fetch(req).await?;
A request that gets no answer (bad URL, network, nothing within 30 s) is a 502, and so is a reply body over 16 MiB.
Desktop and phone apps: use Tauri
Wisp makes no native apps itself. For desktop and phone, use Tauri v2. Two setups work.
A static frontend. wisp build --spa (or --static) writes dist/; Tauri serves it from its own origin, where the absolute /_app/ paths resolve. The service worker registration fails quietly where the webview has none.
{ "build": { "frontendDist": "../dist", "beforeBuildCommand": "wisp build --spa" } }
The server in the app. Call serve_on from the Rust main on a free loopback port and point the window at it. It runs on Tauri's tokio runtime and starts none of its own. allow_hosts goes first so that a web page on another name that was pointed at that port (DNS rebinding) gets a 421, not your app.
let listener = std::net::TcpListener::bind("127.0.0.1:0")?;
let addr = listener.local_addr()?;
wisp::allow_hosts([addr.to_string()])?;
let url = format!("http://{addr}");
tauri::async_runtime::spawn(wisp::serve_on::<App>(listener));
// then open the window at `url`
Is This Page Useful?