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

Wisp

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.

TargetForFrom dist/<target>
cloudflareWorkersnpx wrangler deploy (secrets: npx wrangler secret put WISP_SECRET)
pagesCloudflare Pagesnpx wrangler pages deploy in dist/pages (WISP_SECRET under Settings)
denoDeno Deploydeno deploy --app <name> --prod (local: deno run -A main.ts)
vercelVercelnpx vercel deploy --prebuilt (env var WISP_SECRET)
netlifyNetlifynpx netlify deploy --prod
nodeAmplify, Firebase, Azure, Stormkit, Zeabur, any Node hostnpm start
bunBun (Bun.listen)bun server.mjs
lambdaAWS Lambdabelow

Other hosts (each has a page under Hosting):

HostUse
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.iowisp deploy init docker, fly launch, fly deploy, fly secrets set WISP_SECRET=...
Railway, Renderwisp deploy init docker, point at the repo, set WISP_SECRET
Cloud Runwisp 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.

  • _redirects for Netlify and Cloudflare Pages: /r/:id / 200. It names /, not /index.html, because Cloudflare Pages would answer the latter with a cached 308. Your static/_redirects stays first.
  • vercel.json for Vercel, a rewrites entry per route (/r/:id, /files/:rest*). Your static/vercel.json keeps its rewrites first and gets the missing ones.
  • 404.html, a copy of index.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_version must 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 the js and css of each content_scripts entry. A page path can end with a query or a fragment.
  • A route /popup gives the file popup/index.html, so the manifest names popup/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. /options and /options/ become /options/index.html, and / becomes /index.html. A query and a fragment stay. Chrome does not open a folder URL as its index.html.
  • The build writes no _headers, .nojekyll or 404.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 no src and with text, when its type is JavaScript, module, importmap or speculationrules. A data block such as type="application/json" stays.
  • an attribute whose name starts with on, such as onclick.
  • a javascript: URL in an href, src, action or formaction. 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:

CauseError
no manifest.json in the app foldermanifest.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 /wispsrc/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 guarderror /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_versionmanifest.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 filemanifest.json: action.default_popup is popup, and the output has no file popup
a path that is not a stringmanifest.json: options_page must be a path, not 5
an inline scriptx.html: a <script> with no src. Manifest V3 runs only the code of script files
an on* attributepopup/index.html: the attribute onclick on <button>. Manifest V3 runs only the code of script files
a javascript: URLx.html: a javascript: URL in the attribute href on <a>. Manifest V3 runs only the code of script files
inline code, last line4 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. --edge puts 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/new beside the Edge route item/[id]). In the second, that Edge pattern has a matcher (item/[slug] beside item/[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 route item/[id=int], /item/abc stays 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/b beside the Node route a/[x]). The build warns for each such Edge route, and the Node function serves it.
  • A host build (wisp build --target <host>) also writes the google fonts and the Open Graph cards of wisp::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 with node:http, Bun.serve or Deno.serve (one stderr line says which). Deno Deploy always uses Deno.serve.
  • Only the node:http path caps a body at WISP_BODY_LIMIT (default 1 MB, then 413). The bridges that read with the host's own fetch (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 to cx.body().
  • Through the fetch handler (serve), a pure route answers in one call. A route can be pure when its +server.rs has a sync fn get() with no Cx, no input and no path param. It is pure when no hook, guard, CACHE, COMPRESS, CORS or TIMEOUT is on it. A GET with no query can get a 200 with only a static content-type. Then the bridge keeps the path and host. Later GETs of them run the handler with no request bytes and no Cx. 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:http handler (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, one host that 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_API is set. A plain release build leaves that out. WISP_LAMBDA=1 for a plain cargo build --release keeps it.
  • Lambda freezes the process between invocations, so every and spawn run only while one is answered. wisp::cron and wisp::work run from EventBridge Scheduler schedules in the build's eventbridge.sh (Cron).
  • A stream is sent whole, cut at 25 s or 4 MB. With a RESPONSE_STREAM Function URL and WISP_LAMBDA_STREAM=1 it 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. Use wisp::store for lasting data.
  • The tower feature with lambda_http also works (Testing and mixing with Rust code).

What Works on the Edge

No threads, sockets or files.

TopicRule
Tasks and timersUse 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 storagewisp::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.
SecretsHost secrets. Read them with wisp::env("KEY") (std::env::var sees nothing, and there is no .env).
StreamingResponse::stream and Response::events are live on Cloudflare, Deno, Netlify, Vercel, Node. A client that leaves fails send.
WebSocketsSee below. 501 on Vercel, Netlify and tower: use SSE.
Not in the edge buildwisp::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.
PanicsA 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.

HostWebSockets
binary, Docker, node, bun, deno, cloudflare, pagesyes
lambdayes, behind an API Gateway WebSocket API
vercel501 and a build warning (waits on a deploy test, Host on Vercel)
netlify501 and a build warning (its functions take no upgrade)
tower501 (upgrade in the host framework)
  • On raw sockets the codec is the native server's (WISP_WS_IDLE, the BODY_LIMIT message 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_STOREStore
d1:DBCloudflare D1 binding DB
deno-kvDeno KV (deno-kv:<path> file or URL)
libsql://name.turso.ioTurso 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:

HostTrigger
Cloudflare[triggers] crons in wrangler.toml, with the weekday counted 1 to 7 from Sunday
Vercelcrons in config.json, with the weekday 0 to 6 (Hobby plan: daily only)
Netlifya scheduled function
Cloudflare Pagesa companion Worker in cron/ (Cron on Pages)
Denoa Deno.cron in main.ts
  • A trigger asks the app for /_wisp/cron/<schedule> with Authorization: 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-5 runs 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::cron takes no L, W or # 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 work gets a trigger each minute). Queued jobs need WISP_STORE.
  • Node, Bun, Lambda, Azure Static Web Apps and Netlify --edge have 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?

View This Page's Source

Type to search every docs page and heading.