How a project is laid out
A Voussoir project is two things in one directory: a frontend Bun can bundle, and a Rust crate that embeds the result. The split is deliberate, because the two sides have different failure modes and different reload speeds.
myapp/
voussoir.json configuration, embedded into the binary
index.html entry page; Bun bundles it and everything it imports
src/ frontend: TypeScript, JSX, CSS. Bun handles all of it
native/
Cargo.toml shell crate, depends on `voussoir`
src/main.rs App builder: window, shell-service commands, run
src/assets.rs generated asset table; never edit by hand
commands/
Cargo.toml cdylib in dev, static lib in release
src/lib.rs your command table, hot-reloaded by `voussoir dev`
android/ Gradle project, scaffolded by `init`
ios/ Xcode project, scaffolded by `init`
voussoir.json
{
"name": "Notes",
"title": "Notes",
"width": 900,
"height": 680,
"entry": "index.html",
"commands": ["greet", "save"],
"windows": { "untrusted": { "commands": ["greet"] } }
}
Every key is optional. The file is include_str!-ed into the binary, so a shipped
app never reads configuration from disk, and a writable working directory cannot
redirect it.
nameis the app identity: data directory, bundle name, Android package stem.entryis the page the first window loads. A/prefix is stripped.commandsis the global allowlist. Absent means "everything registered".windowsnarrows one label's surface; see Per-window allowlists.command_timeout_msis how long the page waits for a command before rejecting. Defaults to 30000;0disables the deadline for commands that legitimately run for minutes. A page can override it per call withvoussoir.invoke("slow", payload, { timeout: 300000 }), and read the default asvoussoir.timeout.
native/src/assets.rs
voussoir build and voussoir dev both write this file. It is a table of (path, bytes)
pairs compiled into the binary, which is why the release build has no frontend
directory to lose and no filesystem read on startup. cargo check works in a
fresh checkout because voussoir init writes an empty table first.
Why the command crate is separate
native/commands is a cdylib in development and a static library in release.
Keeping it in its own crate is what makes the hot-reload loop cheap: voussoir dev
rebuilds only that crate and swaps the shared object into the running shell,
without recompiling the shell or restarting the process.
The cost is one rule that matters: statics inside that crate do not survive a
reload, because the library that owned them is unloaded. State that must survive
belongs in voussoir::state, which the shell owns. See
Hot reload.