# Run a Rune app in the browser
Rune's experimental web target renders one canvas through WebGPU. It uses the same Rust
views, layout, glyph atlas and shaders as native. GPU initialization is asynchronous; the
runtime stays on the browser's main thread and requests frames only while work is pending.
## Build the example
Install the wasm target, Python 3.11 or newer, and the wasm-bindgen CLI version in Cargo.lock:
```sh
rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.129 --locked
scripts/web-build.sh web-hello --out target/web
```
Serve the entire output folder over HTTPS, including `snippets/`. A local HTTP server on
`localhost` also works for development. The host must serve `.wasm` as `application/wasm`.
No application server, SharedArrayBuffer, COOP or COEP headers are required.
`--opt` additionally runs an installed `wasm-opt -Oz`; the default build does not need it.
A release build drops the wasm's function-name section, so a panic's stack shows offsets
instead of Rust names; `--names` keeps it for profiling, and `--dev` builds always keep it.
The script prints the raw and gzip wasm sizes. Configure gzip or Brotli on the static host
to get the corresponding transfer size.
```text
usage: web-build.sh PACKAGE [--example NAME] [--out DIR] [--opt] [--dev] [--watch] [--no-html] [--names]
```
The script builds with the toolchain's own cargo (`rustup which cargo`), not a `cargo` wrapper
on `PATH` that might build on another machine, and stops with a message if the wasm isn't in
the local target folder afterwards. Set `CARGO` to pick the cargo binary.
The example is a scrollable message list with a composer, Send and Copy last. Its title
opens an external link. Refreshing resets the in-memory messages.
## Edit and reload
`--dev` builds fast instead of small: the debug profile without debug info, with dependencies
(Rune included) at opt-level 1 and your package unoptimized, in its own `web-dev` target folder
so it never rebuilds the release cache. It skips `--opt`. The wasm is about twice the release
size; don't ship it. On `web-hello`, a one-line change rebuilds in about 2 s, against 12 s for
a release build.
`--watch` rebuilds whenever a file in a workspace member changes (polling, no extra tools), and
the page reloads itself after each successful build. Serve the folder from a second terminal:
```sh
scripts/web-build.sh web-hello --dev --watch
python3 -m http.server 8000 -d target/web # then open http://localhost:8000
```
WebGPU works over plain HTTP on `localhost`; from another machine the page needs HTTPS. In
watch mode the script writes `reload.js`, which polls `.stamp` in the same folder and reloads
when a build changes it, and the generated page cache-busts `app.js` and `app_bg.wasm`. A
failed build leaves the page as it was. Each build stages its files in `.next` and renames them
into place, so a page loading mid-build gets one build's `app.js` and `app_bg.wasm`. Reloading
resets the app's state.
## Your own page
The script writes `index.html` only if there is none, or if the existing one still has the
`generated by rune web-build.sh` comment, so a page of your own (with `App::canvas_id` and
`fit_content_height`, say) is kept. Delete that comment line to keep edits to the generated
page. `--no-html` never writes `index.html`. To reload your own page in watch mode, add
`` while developing.
## Give your app a wasm entrypoint
Add a `cdylib` target and a wasm-only wasm-bindgen dependency:
```toml
[lib]
crate-type = ["cdylib", "rlib"]
[target.'cfg(target_arch = "wasm32")'.dependencies]
wasm-bindgen = "0.2"
```
Export a start function that calls the usual Rune entrypoint:
```rust,ignore
#[cfg_attr(target_arch = "wasm32", wasm_bindgen::prelude::wasm_bindgen(start))]
pub fn start() {
rune::run(AppSpec::new("My app", (390.0, 760.0), State::default, view));
}
```
From your app's workspace, run `path/to/rune/scripts/web-build.sh your-package`. The script
selects one cdylib, or one binary if there is no cdylib. `--example NAME` selects a Cargo
example. Disable Rune's `dev`, `hot` and `native-file-dialog` features on wasm. Move native
filesystem, process and thread dependencies behind target conditions in your app too.
Use `rune::time::Instant` for deadlines passed to Rune; it is `std::time::Instant` on native.
## Luau scripts
An app that hosts Luau with `rune-luau` builds for the web too: Luau's C++ compiles with
[WASI SDK](https://github.com/WebAssembly/wasi-sdk) (33 or newer) against WASI libc, using
WebAssembly exception handling. Unpack the SDK and point `WASI_SDK_PATH` at it; `web-build.sh`
then sets the C and C++ compilers for the wasm target, and `rune-luau` links the SDK's C runtime
and defines the WASI calls libc makes inside the module, so the page loads like any other
Rune app. Luau runs as its interpreter there.
```sh
WASI_SDK_PATH=$HOME/wasi-sdk-34.0 scripts/web-build.sh luau-panel --out target/web-luau
node examples/luau-panel/web-proof.mjs target/web-luau target/web-luau-proof
```
Browsers with exception handling run it: current Chrome, Edge, Firefox and Safari.
## Mount in a page
By default Rune appends its own canvas, covers the viewport and stops the body scrolling.
`App::canvas_id("id")` mounts onto a `