Duolith docs

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 own Cargo.toml (its own workspace) and crate-type = ["cdylib", "staticlib", "rlib"].
  • Pages import it by folder: import { fibonacci } from "../modules/maths". An import of ../ steps then modules/<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.duo writes ../../modules/maths), so pages/modules/maths is never mistaken for it (E0304); ../modules/nope with 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)], with uniffi an optional dependency behind the native feature (UniFFI 0.29.4). examples/rust-module shows the whole shape.
  • **duolith build compiles every module for the web** (crates/cli/src/modules.rs): cargo build --release --target wasm32-unknown-unknown into the project's .duolith/target/ (which the dev server does not watch), then wasm-bindgen --target web. The site gets _duolith/modules/<name>/ with wasm-bindgen's loader, the WebAssembly, and an index.js that awaits the WebAssembly at the top level, so a page's script never sees an unloaded module. The import is rewritten to that index.js. Missing tools are E0300, a crate that does not compile E0301.
  • Types: the build writes modules/<name>/index.d.ts from 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 native and 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/modules holds 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

OptionWhy not
@duolith/modules/<name> or rust:<name> specifiersA relative folder import resolves in plain TypeScript to the generated index.d.ts, with no special resolution in the editor
wasm-packOne more tool to install; wasm-bindgen-cli is already required and pinned
UniFFI for the web tooUniFFI's WebAssembly support is not stable at 0.29
A macro crate that writes both attributesA dependency every module needs before anyone has written a second module; two attributes are plain and searchable
Loading the WebAssembly lazily on first callEvery 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.