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

Wisp

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:

FlagAnswers
--template demo|minimal|api|extension (--api)which template
--[no-]tailwindTailwind
--[no-]tsTypeScript only
--[no-]strictwarnings are build errors
--[no-]typechecktsc on every build
--[no-]gitgit repo
--[no-]installfetch and compile now
--yesall defaults (also when there is no terminal)
--liba 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.json and postcss.config.*, without notify. Dot folders, target, node_modules and 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 bool literal swaps in too (Literal swap). Any other .rs change, an added or removed template, or a Cargo.toml change compiles. A CSS save swaps the stylesheet in place. A .rs file saved with the same tokens prints no code changed and builds nothing.
  • Port. The front of wisp dev listens on the dev port, on HOST (127.0.0.1 unless HOST is set). If the port is in use, wisp dev takes the next free one, up to 20 more, and says so. The app listens on a free loopback port of its own. wisp build servers 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 its listening on line 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 says The app of the build before still serves the requests. Init side effects (timers, wisp::spawn loops, 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, then WISP_DRAIN and 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 dev stops the old app, and the front holds new requests until the new app listens. A held request waits at most 70 s, or WISP_DRAIN and 23 s when that is longer. If the new app then fails to start, wisp dev starts 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 dev stays open.
  • Client address. The front passes Host, Origin and the X-Forwarded-* headers to the app as the client sent them. It names the client in x-wisp-peer with 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, so cx.peer() is the client, as with no front. A release build has no such code. Under --https, the front adds x-forwarded-proto: https for 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 a Host that is an IP address, localhost, a *.localhost name or one in WISP_DEV_ORIGIN, else 403 (against DNS rebinding). This holds for the app, its WebSockets and event streams, and each proxy target. Under wisp dev with a HOST other 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 dev ended, the app stops as on SIGTERM and frees the port. A CSS watcher runs under wisp __child <exe> <args...>, which kills the tool then.
  • Reload. wisp dev serves 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 without wisp.js (CSR = false, or scripts = 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 and file: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, a src/lib.rs, a build.rs other than wisp_build::run(), or a rustc wrapper, and whenever a failure names none of the app's files.
  • WISP_DEV_CARGO=1 always uses cargo. On Linux the replay is used only after it has rebuilt the binary once with nothing changed. On macOS it is off, and WISP_DEV_DIRECT=1 turns it on.
  • It links with rust-lld on Windows and with mold on Linux when installed, and leaves debug info out unless RUST_BACKTRACE is set. A panic keeps its file:line.
  • It compiles the app crate with -C opt-level=0 -C codegen-units=16 when the profile has opt-level 0 or 1 (the scaffold has 1). A higher opt-level stays as the app sets it. The dependencies keep the profile. wisp build and 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

SetupWhat runs
src/app.css imports TailwindTailwind standalone --watch into .wisp/app.css
src/app.scss existsDart 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)
nonesrc/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 nearest Cargo.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 in x = {}/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>1 stays x>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. A url( 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 a type attribute, 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\n line ends keeps them. A file that mixes \r\n and a bare \n stays as written, because the bare \n can 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_SECRET under 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 the x-wisp-dev header the CLI sends. A request a proxy or tunnel passed on (forwarded, x-forwarded-for, x-real-ip) is refused even with Host rewritten to localhost, so never serve a debug build behind a proxy. The dev events stream also answers hosts listed in WISP_DEV_ORIGIN (comma-separated).
  • URL attributes. javascript: and vbscript: are blocked in href={:x} and :src="x" as in href=${x}. wisp.js never follows a javascript: redirect or goto.
  • Limits. Size and time limits are in Runtime and build. Chunked bodies are parsed strictly and Content-Length with Transfer-Encoding is rejected, so there is no request smuggling surface.
  • Connections. At most WISP_MAX_CONNS are 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 (cgroup memory.max in 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.rs sends malformed, oversized, smuggling and cross-site requests, path traversal and junk cookies to the demo's binary, and checks that it keeps answering. tests/app does 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 or src/app.html). No hole can go in one, so the build hashes each and script-src lists the hashes.
  • A page that calls cx.nonce() gets a per-request nonce and cache-control: private, no-store.
  • Dev mode adds https://esm.sh to script-src and connect-src, and wisp dev's reload events to connect-src.
  • wisp::csp("img-src 'self' https://cdn.example; font-src https://f.example") in init replaces the default of each directive it names, or adds it. script-src keeps the hashes. The build already adds the https origins your templates, shell, CSS and fonts.txt load 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 after init and log that.
  • Not covered: endpoints, Response::html, /_wisp/docs, and wisp build --static (files have no headers, so the host sets them). A script from {@html} or an onclick="..." attribute does not run. Use a file, or on: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.

  1. Core: routes, layouts, templates, load, actions, errors, static files, wisp.js morph, wisp dev with hot swap. (done)
  2. Measure: req/s and latency against Rust and Node frameworks on the same machine (Benchmarks). (in progress)
  3. 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)
  4. v0.2: link boosting (the client router) and a docs site built with Wisp (this one). (done)

Is This Page Useful?

View This Page's Source

Type to search every docs page and heading.