How to Add WebAssembly Support to a General-Purpose Crate

This section is for general-purpose crate authors who want to supportWebAssembly.

Maybe Your Crate Already Supports WebAssembly!

Review the information about what kinds of things can make a general-purposecrate not portable for WebAssembly. Ifyour crate doesn't have any of those things, it likely already supportsWebAssembly!

You can always check by running cargo build for the WebAssembly target:

  1. cargo build --target wasm32-unknown-unknown

If that command fails, then your crate doesn't support WebAssembly right now. Ifit doesn't fail, then your crate might support WebAssembly. You can be 100%sure that it does (and continues to do so!) by adding tests for wasm andrunning those tests in CI.

Adding Support for WebAssembly

Avoid Performing I/O Directly

On the Web, I/O is always asynchronous, and there isn't a file system. FactorI/O out of your library, let users perform the I/O and then pass the inputslices to your library instead.

For example, refactor this:

  2. # #![allow(unused_variables)]
  3. #fn main() {
  4. use std::fs;
  5. use std::path::Path;
  7. pub fn parse_thing(path: &Path) -> Result<MyThing, MyError> {
  8.     let contents = fs::read(path)?;
  9.     // ...
  10. }
  11. #}

Into this:

  2. # #![allow(unused_variables)]
  3. #fn main() {
  4. pub fn parse_thing(contents: &[u8]) -> Result<MyThing, MyError> {
  5.     // ...
  6. }
  7. #}

Add wasm-bindgen as a Dependency

If you need to interact with the outside world (i.e. you can't have libraryconsumers drive that interaction for you) then you'll need to add wasm-bindgen(and js-sys and web-sys if you need them) as a dependency for whencompilation is targeting WebAssembly:

  1. [target.'cfg(target_arch = "wasm32")'.dependencies]
  2. wasm-bindgen = "0.2"
  3. js-sys = "0.3"
  4. web-sys = "0.3"

Avoid Synchronous I/O

If you must perform I/O in your library, then it cannot be synchronous. There isonly asynchronous I/O on the Web. Use the futurescrate and the wasm-bindgen-futurescrate tomanage asynchronous I/O. If your library functions are generic over somefuture type F, then that future can be implemented via fetch on the Web orvia non-blocking I/O provided by the operating system.

  2. # #![allow(unused_variables)]
  3. #fn main() {
  4. pub fn do_stuff<F>(future: F) -> impl Future<Item = MyOtherThing>
  5. where
  6.     F: Future<Item = MyThing>,
  7. {
  8.     // ...
  9. }
  10. #}

You can also define a trait and implement it for WebAssembly and the Web andalso for native targets:

  2. # #![allow(unused_variables)]
  3. #fn main() {
  4. trait ReadMyThing {
  5.     type F: Future<Item = MyThing>;
  6.     fn read(&self) -> Self::F;
  7. }
  9. #[cfg(target_arch = "wasm32")]
  10. struct WebReadMyThing {
  11.     // ...
  12. }
  14. #[cfg(target_arch = "wasm32")]
  15. impl ReadMyThing for WebReadMyThing {
  16.     // ...
  17. }
  19. #[cfg(not(target_arch = "wasm32"))]
  20. struct NativeReadMyThing {
  21.     // ...
  22. }
  24. #[cfg(not(target_arch = "wasm32"))]
  25. impl ReadMyThing for NativeReadMyThing {
  26.     // ...
  27. }
  28. #}

Avoid Spawning Threads

Wasm doesn't support threads yet (but experimental work isongoing),so attempts to spawn threads in wasm will panic.

You can use #[cfg(..)]s to enable threaded and non-threaded code pathsdepending on if the target is WebAssembly or not:

  2. # #![allow(unused_variables)]
  3. #![cfg(target_arch = "wasm32")]
  4. #fn main() {
  5. fn do_work() {
  6.     // Do work with only this thread...
  7. }
  9. #![cfg(not(target_arch = "wasm32"))]
  10. fn do_work() {
  11.     use std::thread;
  13.     // Spread work to helper threads....
  14.     thread::spawn(|| {
  15.         // ...
  16.     });
  17. }
  18. #}

Another option is to factor out thread spawning from your library and allowusers to "bring their own threads" similar to factoring out file I/O andallowing users to bring their own I/O. This has the side effect of playing nicewith applications that want to own their own custom thread pool.

Maintaining Ongoing Support for WebAssembly

Building for wasm32-unknown-unknown in CI

Ensure that compilation doesn't fail when targeting WebAssembly by having yourCI script run these commands:

  1. rustup target add wasm32-unknown-unknown
  2. cargo check --target wasm32-unknown-unknown

For example, you can add this to your .travis.yml configuration for Travis CI:

  2. matrix:
  3.   include:
  4.     - language: rust
  5.       rust: stable
  6.       name: "check wasm32 support"
  7.       install: rustup target add wasm32-unknown-unknown
  8.       script: cargo check --target wasm32-unknown-unknown

Testing in Node.js and Headless Browsers

You can use wasm-bindgen-test and the wasm-pack test subcommand to run wasmtests in either Node.js or a headless browser. You can even integrate thesetests into your CI.

Learn more about testing wasmhere.