0078. Rust modules live in modules/<name>/, are imported by folder, and are built with wasm-bindgen and UniFFI
- Status: Accepted (Mik, 17 Nov 2026)
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: WP13 (Rust modules through UniFFI), WP9 (a Rust module called from iOS, Android and web)
Context
Rung 3 of the ladder is code an app author writes in Rust. A page's script must call it with types on every target: the web through WebAssembly, iOS and Android through generated Swift and Kotlin. UniFFI generates the native bindings; wasm-bindgen is already the repository's WebAssembly binder (decision 0025, pinned at 0.2.130).
Decision
- **A Rust module is a crate in the project's
modules/<name>/**, with its ownCargo.toml(its own workspace) andcrate-type = ["cdylib", "staticlib", "rlib"]. - Pages import it by folder:
import { fibonacci } from "../modules/maths". An import of../steps thenmodules/<name>(letters, digits,-and_; no extension) is a Rust module import. The build checks that the steps lead from the file to the project root, one per folder (pages/a/b.duowrites../../modules/maths), sopages/modules/mathsis never mistaken for it (E0304);../modules/nopewith no such folder is E0303, from a page or a component. - Each exported function carries two attributes,
#[cfg_attr(target_arch = "wasm32", wasm_bindgen)]and#[cfg_attr(feature = "native", uniffi::export)], withuniffian optional dependency behind thenativefeature (UniFFI 0.29.4).examples/rust-moduleshows the whole shape. - **
duolith buildcompiles every module for the web** (crates/cli/src/modules.rs):cargo build --release --target wasm32-unknown-unknowninto the project's.duolith/target/(which the dev server does not watch), thenwasm-bindgen --target web. The site gets_duolith/modules/<name>/with wasm-bindgen's loader, the WebAssembly, and anindex.jsthat awaits the WebAssembly at the top level, so a page's script never sees an unloaded module. The import is rewritten to thatindex.js. Missing tools are E0300, a crate that does not compile E0301. - Types: the build writes
modules/<name>/index.d.tsfrom wasm-bindgen's declarations, without the loader, with a generated header, only when it changes. TypeScript resolves the folder import to it, so the page's script and the editor type-check calls (fibonacci("ten")is an error). - Native bindings come from
pnpm --filter @duolith/modules bindings:native modules/<name>: it builds the crate for the build machine with--features nativeand runs UniFFI's generator (packages/modules/native/uniffi-bindgen, pinned to the same UniFFI) into.duolith/bindings/<name>/{swift,kotlin}. This works on any machine. Compiling for and running on devices needs Xcode and the NDK:native/DEVICE-CHECKLIST.md. packages/modulesholds the TypeScript side: reading a module's functions from its declarations, and the compatibility verdict per target (ready on the web once built; on iOS and Android, a device away).- The build report lists each module on rung 3, with its sizes and the files that use it (decision 0079).
Alternatives considered
| Option | Why not |
|---|---|
@duolith/modules/<name> or rust:<name> specifiers | A relative folder import resolves in plain TypeScript to the generated index.d.ts, with no special resolution in the editor |
| wasm-pack | One more tool to install; wasm-bindgen-cli is already required and pinned |
| UniFFI for the web too | UniFFI's WebAssembly support is not stable at 0.29 |
| A macro crate that writes both attributes | A dependency every module needs before anyone has written a second module; two attributes are plain and searchable |
| Loading the WebAssembly lazily on first call | Every function would become asynchronous, which changes the module's types |
Consequences
- Building a project with a module needs Rust, the wasm32 target and wasm-bindgen-cli; CI's Rust job installs them to build
examples/rust-module. - A module's first build compiles its dependencies (about 20 seconds for the example); later builds are incremental.