CLI, Dev Loop and Security
wisp new my-app # prompts, or flags
cd my-app
wisp dev # hot swap, live errors
wisp fmt # format .wisp files
wisp build # release binary
wisp build --fast is for CI, previews and iteration. For that one cargo run it sets CARGO_PROFILE_RELEASE_LTO=thin, CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 and CARGO_INCREMENTAL=1. Deploy and benchmark plain wisp build. It works with a binary build, --static and --target native, and is an error with another --target or --analyze.
Release builds minify the browser JavaScript the app owns: component modules, src/lib modules and +page.js load modules (comments and whitespace go, but names stay). The result is checked: if its tokens differ from the source's, or a line break that ends a statement is lost, the module is served as written. wisp build --sourcemap skips minification, so the maps match the files, and a last //# sourceURL= line is kept so traces name the .wisp file. Debug builds serve modules as written.
Agents (wisp mcp, wisp update-docs) and editors (wisp lsp): AI agents and editors.
wisp new
wisp new [name] asks where the app goes and which template: Demo (a counter, an about page and Wisple, a word game on form actions), Minimal (one page, a layout and an error page) or API (a JSON API with notes, validation, an API key, live events and docs). It then asks about Tailwind, TypeScript only, warnings as errors, type-checking on every build (Config), a git repo and installing dependencies now. Flags answer the same questions:
| Flag | Answers |
|---|---|
--template demo|minimal|api|extension (--api) | which template |
--[no-]tailwind | Tailwind |
--[no-]ts | TypeScript only |
--[no-]strict | warnings are build errors |
--[no-]typecheck | tsc on every build |
--[no-]git | git repo |
--[no-]install | fetch and compile now |
--yes | all defaults (also when there is no terminal) |
--lib | a component library, not an app |
It never writes into a folder that has files in it, and refuses a name Cargo rejects or that collides with Wisp's crates. An app created inside another Cargo workspace gets an empty [workspace] table, so it builds alone. Apps depend on Wisp by path when wisp was built from a clone, and on https://wisp.ar0.eu/ when installed with cargo install --git.
wisp dev
wisp dev [--port <n> | --port=<n> | -p <n>] [--https] [--target node|bun|deno] is one process with TLS (rustls with ring, no OpenSSL) only for --https and the https:// proxy targets. -p 0 takes a free port once and keeps it. To send some paths to an API on another port, use [package.metadata.wisp.dev.proxy] (Config). --https listens with TLS on the dev port through the front and passes plain HTTP to the app, so the app and its request path are unchanged. If a CSS tool cannot start, it says so and serves on without fresh CSS.
--target node|bun|deno runs the app through that host's glue, built into .wisp/emulate/<host>. A save rebuilds the wasm and restarts it (seconds, no hot swap). wisp preview builds the release binary and runs it as deployed (port 4173). wisp preview --static|--spa exports the site and serves the folder like a static host. See /docs/cli.
- Watching. It polls mtimes of
src/,static/,Cargo.toml,build.rs,package.jsonandpostcss.config.*, withoutnotify. Dot folders,target,node_modulesand editor swap files are skipped. A save is built once, even from an editor that deletes then renames. - A save swaps or compiles. A changed template swaps in with no compile (Template hot swap). A changed string, number or
boolliteral swaps in too (Literal swap). Any other.rschange, an added or removed template, or aCargo.tomlchange compiles. A CSS save swaps the stylesheet in place. A.rsfile saved with the same tokens printsno code changedand builds nothing. - Port. The front of
wisp devlistens on the dev port, onHOST(127.0.0.1unlessHOSTis set). If the port is in use,wisp devtakes the next free one, up to 20 more, and says so. The app listens on a free loopback port of its own.wisp buildservers never move. - Swap. The exe is copied to
.wisp/run/so the next build can overwrite the original while the old server runs. A save that compiles starts the new app beside the old one. The new app is ready when it prints itslistening online and answers a request. Then the front sends new requests to it, and the old app stops after the requests it has (WISP_DRAIN, 10 s). So a save drops no request. A new app that fails to start leaves the old one, and the terminal saysThe app of the build before still serves the requests.Init side effects (timers,wisp::spawnloops, jobs) run in both apps while they overlap, from the start of the new app until the old app stops. After the new app listens, that is up to 10 s for the health check, thenWISP_DRAINand 3 s. - Saved tables. One process at a time holds the data folder (
.wisp/data). A new app that needs it prints a line,wisp devstops the old app, and the front holds new requests until the new app listens. A held request waits at most 70 s, orWISP_DRAINand 23 s when that is longer. If the new app then fails to start,wisp devstarts the old one again. - Streams. The old app ends its event streams and closes its WebSockets when it stops. A client that connects again reaches the new app. The reload stream of
wisp devstays open. - Client address. The front passes
Host,Originand theX-Forwarded-*headers to the app as the client sent them. It names the client inx-wisp-peerwith a token of the run, and deletes a copy that a client sends. A debug build takes that header only with the token and from a loopback peer, socx.peer()is the client, as with no front. A release build has no such code. Under--https, the front addsx-forwarded-proto: httpsfor a client that is not loopback or that sends a forwarding header. A request for the app with no body keeps both connections open for the next request when the answer has a length. The front keeps at most 8 idle connections to the app. The front serves only aHostthat is an IP address,localhost, a*.localhostname or one inWISP_DEV_ORIGIN, else 403 (against DNS rebinding). This holds for the app, its WebSockets and event streams, and each proxy target. Underwisp devwith aHOSTother than loopback, the app signs with a key of its own process, not.wisp/secret(WISP_DEV_FRONT). - Cleanup. The app's stdin is a pipe the CLI holds. When it closes, however
wisp devended, the app stops as on SIGTERM and frees the port. A CSS watcher runs underwisp __child <exe> <args...>, which kills the tool then. - Reload.
wisp devserves a Server-Sent Events stream on its own port. Browsers stay connected across swaps and morph or reload when the new app is ready. A page withoutwisp.js(CSR = false, orscripts = false) always reloads. A reload keeps the scroll of the window and of each scrolled element with an id (same address, within 5 seconds). - Output. One line per change (
~ src/routes/+page.wisp swapped in 0ms,✓ Rebuilt in 0.3 s). Compiler errors use paths relative to the app, and an error in generated code is retold against the template's line. - Request log. The app logs each request in dev (
GET /nope 404 0.1ms) and a handler's panic once, with its message andfile:line. Release builds log only 5xx.
Rust Edits Skip Cargo
On Windows and Linux, the first build runs cargo with wisp as RUSTC_WRAPPER and records how cargo ran rustc, in .wisp/run/rustc. Later saves of the app's .rs and .wisp files run that command again with the same incremental cache. That skips cargo's own start and the build script.
- It falls back to cargo for an app with plugins or
extends, asrc/lib.rs, abuild.rsother thanwisp_build::run(), or a rustc wrapper, and whenever a failure names none of the app's files. WISP_DEV_CARGO=1always uses cargo. On Linux the replay is used only after it has rebuilt the binary once with nothing changed. On macOS it is off, andWISP_DEV_DIRECT=1turns it on.- It links with
rust-lldon Windows and withmoldon Linux when installed, and leaves debug info out unlessRUST_BACKTRACEis set. A panic keeps itsfile:line. - It compiles the app crate with
-C opt-level=0 -C codegen-units=16when the profile hasopt-level0 or 1 (the scaffold has 1). A higheropt-levelstays as the app sets it. The dependencies keep the profile.wisp buildand a cargo build do not change. A save that changes a function body compiles faster, and a request in the dev server takes a little longer. The changelog has the numbers and the method.
CSS Tools
| Setup | What runs |
|---|---|
src/app.css imports Tailwind | Tailwind standalone --watch into .wisp/app.css |
src/app.scss exists | Dart Sass (pinned in ~/.wisp/bin, $WISP_SASS overrides) --watch |
a postcss.config.* | the tool writes .wisp/pre.css, then the app's node_modules/postcss-cli makes .wisp/app.css (no npx) |
| none | src/app.css served as written |
wisp build runs each tool once, minified.
NPM Imports
Bare imports ('canvas-confetti') are NPM packages. package.json pins exact versions (wisp npm add). Dev imports https://esm.sh/pkg@v?target=es2022. wisp build downloads the imported modules and what they import into .wisp/npm and embeds them under /_app/c/npm/. Paths name versions, so they are cached for good. npm.lock holds the SHA-256 of each file: a file with other bytes fails the build, and a new file gets a line. Commit it.
A build makes an empty static/ when the app has none (not under cargo package, or where the folder cannot be written), so that files put in it later are embedded by the next cargo build without a change under src/.
Template Hot Swap
In debug builds the static HTML chunks of every template are read through a table instead of being literals. On a .wisp save, the CLI POSTs the new chunks to the app (/_wisp/dev/swap, loopback only) and the browser morphs, with no compile. This works when only static text changed, or compiled parts (holes, attributes, {#if}/{#each}/{#match}, components) were dropped. A new or moved hole, or a changed block, props or browser code, compiles, and the terminal names the file and line. Release builds have no table. A release edge wasm build has no /_wisp/* dev endpoint: the app's router answers those paths (its own 404 page when no route matches).
Literal Swap
wisp dev builds with WISP_LITS=1, which reads the app's plain string literals from a table. When a save changes only such literals, the CLI sends them to the app (/_wisp/dev/lits, loopback only), browsers reload with $state kept, and the terminal says 1 literal swapped in 0ms. Literals in attributes, macros (format!), const and static items, patterns and raw, byte and C strings are not in the table, so changing them compiles. The table holds the literals of .rs files and of a .wisp --- block: its functions and its top-level statements (let n = 5;). Number and bool literals (3 + 4, 1.5, true) swap the same way through wisp::rt::val. An integer with no suffix swaps up to 127, because each integer type holds that value. An integer with a suffix swaps in the range of its type. A float swaps when it is finite. Any other value compiles. Array lengths, enum bodies, tuple indexes (t.0), first generic arguments (::<3>), borrows (&5, &[1, 2]), casts (97 as char) and literals with a method call (2.max(x)) are not in the table. A place that the table misses (g::<u8, 3>()) fails the build. Then wisp dev builds again without the table and says Wisp cannot swap in a literal. Release builds never have the table.
Logic Edits
A save that changes only literals in the table swaps in place, as the section above shows. Any other change to Rust code compiles the app again and starts the new binary. This includes a function body, a signature, a struct layout, a new static, generics, async code, a macro or a dependency. The new process does not keep in-memory state. $state in the browser stays.
Wisp does not patch machine code in the running process. A patch must compile the app to objects, find the changed functions, link them into a small library and load it. We measured each step on Windows with examples/demo (lane hotpatch3, 2026-11-05). The compile to objects, the wisp_build::hot step and the link of a small library together take more than the time goal for a patch, before the diff, the load and the redirect. The goal was a reload in under one third of a second, so Wisp keeps the compile path. On Windows, a DLL also cannot resolve its symbols to the addresses of a running .exe unless the .exe exports them. Linux was not measured.
Dev Timings
Time from save until a request serves the change, medians of 3 runs on the 4-core bench box (bench/build/README.md, Status, release 1.0.0-pre.3, Wisp 0d2d15a0): a logic edit shows in 1 ms (Wisp is #1) and a template edit in 48 ms (Wisp is #2, SvelteKit 14 ms).
wisp fmt
wisp fmt [paths] formats .wisp files. --check lists the unformatted and fails. wisp fmt --stdin [path] formats stdin to stdout, for editors and editors/prettier-plugin-wisp.
- Elements and template blocks indent two spaces a level, with double-quoted attributes. A start tag goes on one line or, past 100 columns, an attribute a line.
- The
---block goes through rustfmt with the edition of the nearestCargo.toml. <script>gets indentation by bracket and by continuation line, one space round binary operators and after,and;, and line breaks after;. A bracket pair on one line with a,inside breaks, an item a line, when the line is longer than 100 columns. The formatter adds no semicolon and deletes none, and it deletes no line break. A template literal stays as written, and the code in its${}gets the spacing. A comment keeps its words, and its lines get new indentation. A/after a}that the formatter reads as a regex (as inx = {}/1//2) stops the layout of that<script>. A<or>keeps the spacing of the source when the code could read it as a type bracket (x>1staysx>1). A{}block on one line with no;inside stays on one line when it fits in 100 columns.<style>gets one selector and one declaration a line, one space after:and,, and nested rules and at-rules indented. A string,url()and the value of a custom property (--x) keep their text. A comment between rules keeps its text. A block comment whose lines each start with*gets new indentation, line by line. A comment inside a selector or a declaration stops the layout of that<style>: the formatter only re-indents it and prints no warning. Aurl(with no)and an escaped space also stop the layout.- The formatter checks each script and style. The tokens must equal the tokens of the source, and a second format must change nothing. If a check fails, the formatter only re-indents that body and warns once on stderr. A
<script>with atypeattribute, and a body that shares a line with its tag, stay as written. - Text, holes,
<pre>and<textarea>are never touched. - A file with
\r\nline ends keeps them. A file that mixes\r\nand a bare\nstays as written, because the bare\ncan be text of a template literal. - Markup that does not balance is left as written. Formatting twice equals formatting once.
CLI Older Than the App
When the installed wisp is older than the app's wisp crate, app commands warn on stderr. In a terminal they ask Continue anyway? [y/N]. In CI or a pipe they warn and continue. WISP_NO_UPDATE_CHECK=1 silences it. wisp dev, wisp build and wisp new also print a line when a newer release is out (looked up once a day in the background, never in the server); wisp upgrade installs it and bumps the app. See Updating.
cargo install --git https://wisp.ar0.eu/ --tag v1.0.0-pre.3 wisp-web
Add --force to replace an installed wisp. To install a checkout:
cargo install --path <checkout>/crates/wisp-cli --force # path checkout
Prerequisites for each system and the pinned-tag install are on Downloads. What changed in each version is on Changelog.
Security
- Escaping. On by default.
{@html}is the only raw output. - Actions. Opt-in (
#[action]), same-origin checked, and they read only form fields: no client-supplied type names or serialized state. - Signed cookies. The signature binds the cookie's name and value. A
WISP_SECRETunder 32 characters stops the server at start. - Dev endpoints. Debug builds only. They answer only loopback peers with a loopback
Host, so a DNS-rebinding page gets a 403. The template swap also needs thex-wisp-devheader the CLI sends. A request a proxy or tunnel passed on (forwarded,x-forwarded-for,x-real-ip) is refused even withHostrewritten tolocalhost, so never serve a debug build behind a proxy. The dev events stream also answers hosts listed inWISP_DEV_ORIGIN(comma-separated). - URL attributes.
javascript:andvbscript:are blocked inhref={:x}and:src="x"as inhref=${x}. wisp.js never follows ajavascript:redirect orgoto. - Limits. Size and time limits are in Runtime and build. Chunked bodies are parsed strictly and
Content-LengthwithTransfer-Encodingis rejected, so there is no request smuggling surface. - Connections. At most
WISP_MAX_CONNSare open, WebSockets included. Unset, on Linux it is the open-file limit (soft raised to hard at start) less 1024, within a quarter of memory (cgroupmemory.maxin a container) at 16 KiB each; elsewhere 10000. The startup line warns under 16384. Past it a new connection gets a 503 before it costs a task. - Tests.
examples/demo/tests/http.rssends malformed, oversized, smuggling and cross-site requests, path traversal and junk cookies to the demo's binary, and checks that it keeps answering.tests/appdoes the same for hooks, state, uploads, signed cookies, chunked bodies, body limits and streamed responses.
Content Security Policy
Every page and error page (rendered, baked or kept by CACHE) gets:
content-security-policy: default-src 'self'; script-src 'self' 'sha256-…';
style-src 'self' 'unsafe-inline'; img-src 'self' data: https:;
connect-src 'self'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'
- Wisp's own scripts are files (
wisp.js,live.js, modules under/_app/c/). - The only inline scripts are yours (
<script defer>...</script>in a template orsrc/app.html). No hole can go in one, so the build hashes each andscript-srclists the hashes. - A page that calls
cx.nonce()gets a per-request nonce andcache-control: private, no-store. - Dev mode adds
https://esm.shtoscript-srcandconnect-src, andwisp dev's reload events toconnect-src. wisp::csp("img-src 'self' https://cdn.example; font-src https://f.example")ininitreplaces the default of each directive it names, or adds it.script-srckeeps the hashes. The build already adds the https origins your templates, shell, CSS andfonts.txtload scripts, stylesheets, fonts, media and frames from (a CDN<script src>just works); a directive you name here is yours alone (details).wisp::csp_off()sends none. Both do nothing afterinitand log that.- Not covered: endpoints,
Response::html,/_wisp/docs, andwisp build --static(files have no headers, so the host sets them). A script from{@html}or anonclick="..."attribute does not run. Use a file, oron:click.
Non-Goals and Milestones
Wisp has no auth, ORM or job system of its own. It gives the tools (cookies, sessions, the Store trait, hooks, wisp::spawn from init) and the app builds on them. Integrations are recipes in add/ that wire in existing crates (wisp recipe add sqlite). HTTP/2 is the opt-in h2 feature, h2c only.
- Core: routes, layouts, templates, load, actions, errors, static files,
wisp.jsmorph,wisp devwith hot swap. (done) - Measure: req/s and latency against Rust and Node frameworks on the same machine (Benchmarks). (in progress)
- Flexible: hooks, state, components, uploads, signed cookies, streaming, body limits, proxies. (done) Reactive and everywhere: client scripts, router, tower, static export, Docker, edge targets. (done)
- v0.2: link boosting (the client router) and a docs site built with Wisp (this one). (done)
Is This Page Useful?