A minimalist Rust WebAssembly project template

Overview

MiniWASM - A minimalist Rust WebAssembly project template

This is a minimal Rust-powered WebAssembly application template. It was designed to showcase what must be done to get Rust-powered WebAssembly going with only a small amount of code, while still providing useful tools, such as integration with console.log.

How to build?

The easiest way is to install Docker on your system and run the docker-shell.sh script. This script builds a Docker image containing Rust, the wasm32-unknown-unknown target, and a couple of dependencies for optimizing the generated .wasm files.

After building the Docker image the script then launches a container with that image, giving you a shell with a proper build environment. Alternatively you can just install Rust and the wasm32 target on your host machine, and also install binaryen and wabt.

Either way, after opening a shell with a build environment, you can just run the build.sh script. This builds the miniwasm.wasm file and runs it through the optimizer to reduce the file size.

Now that you have the compiled WebAssembly file you can run the serve.sh script. This runs a web server in the current working directory (thanks to Python). You can then go to http://localhost:8000/ to view the application. Open the console to see the log messages that the WebAssembly produces.

Why not wasm-bindgen or wasm-pack?

Wasm-bindgen is awesome, so use it when you can. I myself am working on projects that have more strict performance requirements, and wasm-bindgen's translation layer often gets in the way of performance when I need to pass data back and forth between Rust and JavaScript. Therefore I created MiniWASM as a template to quickly prototype new experiments for my algorithms.

Another reason why you might want to use MiniWASM as a starting point is that you want to build something small and don't want to depend on wasm-pack's NPM packages.

Compatibility

This application template should be compatible with all modern browsers. However, it has only been tested with Chrome 88 and Safari 14. It will probably work fine in Firefox too though.

Technical details

This project consists of two components:

  1. A Rust file serving as the entry point for the WebAssembly application.
  2. An HTML file with embedded JavaScript code to bootstrap the WebAssembly application.

The Rust WebAssembly application

The Rust WebAssembly application is a single-file crate that performs a few functions:

  1. It sets up wee_alloc as the memory allocator.

  2. It has a bridge to send log messages to JavaScript. This is done by importing some proxy functions (one for console.log and one for console.error) and calling them with the address and length of a &str.

    The JavaScript implementation of these functions then looks into the WebAssembly application's WebAssembly.Memory instance and extracts the characters, converting the raw bytes back into a JavaScript-representation before handing them off to the JavaScript console functions.

  3. It defines a struct that holds the application's global state and stores this in a cell in thread local storage.

  4. It defines functions that act as a bridge between the WebAssembly module's external interface and the application struct.

  5. It has a bootstrapping function that sets up a new panic handler so that we can see panics in the JavaScript console.

JavaScript bootstrapping code

Instantiating a WebAssembly module is easy. We just have to fetch the .wasm file and pass its contents into WebAssembly.instantiate.

To get logging to work we need to do a little bit more though. When instantiating the WebAssembly module we provide an import descriptor that exposes console.log and console.error. We can't expose those functions directly though, because WebAssembly's calling convention only allows us to use primitive types as arguments and return values. Therefore we wrap the logging functions with a function that takes the location of a string slice and extracts the bytes from the WebAssembly application's Memory instance. These bytes are converted into a JavaScript string and then handed off to the logging function.

License

Copyright 2021 Emil Loer.

This project is licensed under the MIT license. A copy of the license can be found in the project repository.

You might also like...
Template for Cargo based SysY compiler projects.

基于 Cargo 的 SysY 编译器项目模板 该仓库中存放了一个基于 Cargo 的 SysY 编译器项目的模板, 你可以在该模板的基础上进行进一步的开发. 该仓库中的 Rust 代码实现仅作为演示, 不代表你的编译器必须以此方式实现. 如你需要使用该模板, 建议你删掉所有 Rust 源文件, 仅

finch - a super fast and efficient template rendering engine for node.js

finch A super fast and efficient template rendering engine for node.js, inspired by Handlebars. Usage Finch is very simple to use: Register a template

Balsa is a delightfully simple HTML template engine

🌳 balsa Balsa is a delightfully simple HTML template engine. It is designed to be used in user interfaces such as a CMS where a user needs to be able

Bevy GitHub CI Template

Bevy GitHub CI Template This repo show how to setup CI on a github project for Bevy. It creates two workflows: CI Release CI Definition: .github/workf

This is a template repo for eframe, a framework for writing apps using egui.

eframe template This is a template repo for eframe, a framework for writing apps using egui. The goal is for this to be the simplest way to get starte

Rust templating with Handlebars

handlebars-rust Handlebars templating language implemented in Rust and for Rust. Handlebars-rust is the template engine that renders the official Rust

:pencil: Compile-time HTML templates for Rust

maud Documentation (source) • API reference • Change log Maud is an HTML template engine for Rust. It's implemented as a macro, html!, which compiles

A macro-based html builder for rust

Horrorshow A macro-based html templating library, compatible with stable rust (currently requires rust = 1.37). Features This crate will degrade grac

Rust Compiled Templates with static-file handling

Rust Compiled Templates — ructe This is my attempt at writing a HTML template system for Rust. Some inspiration comes from the scala template system u

Owner
Emil Loer
Freelance software consultant
Emil Loer
Yarte stands for Yet Another Rust Template Engine

Should we start to worry? bytes-buf feature can produce SIGILL. avx and sse flags are in almost all cpus of x86 and x86_64 architectures. More details

Juan Aguilar 249 Dec 19, 2022
A template engine for Rust based on Jinja2/Django

Tera Tera is a template engine inspired by Jinja2 and the Django template language. <title>{% block title %}{% endblock title %}</title> <ul> {% for u

Vincent Prouillet 2.5k Jan 1, 2023
A flexible template engine for Rust

Rustache Rustache is a Rust implementation of the Mustache spec. Documentation The different Mustache tags are documented at the mustache(5) man page.

rustache 208 May 10, 2022
A template for a Rust-powered static-page Try Online interface

rust-tio-template A template for a Rust-powered static-page Try Online interface What is included This is an example setup that enables all of the fol

null 2 Dec 13, 2021
MiniJinja is a powerful but minimal dependency template engine for Rust

MiniJinja: a powerful template engine for Rust with minimal dependencies MiniJinja is a powerful but minimal dependency template engine for Rust which

Armin Ronacher 686 Jan 5, 2023
A "Hello, world!" template of a Rust binary crate for the ESP-IDF framework.

Rust on ESP-IDF "Hello, World" template A "Hello, world!" template of a Rust binary crate for the ESP-IDF framework. This is the crate you get when ru

Ivan Markov 140 Jan 4, 2023
A template for creating services in Rust using Axum and Prisma.

A template for creating services in Rust using Axum and Prisma. This uses the super cool Prisma Rust Client.

Aaron Leopold 6 Oct 19, 2022
Compiler for Jade-like template language to cito.js-based virtual dom

Marafet A very experimental DSL for creating (mostly) single page applications in HTML. It's mostly a Jade-like (or Haml-like) templating language wit

Paul Colomiets 11 Jun 25, 2020
A nice template for NEAR repos

Template for a NEAR project If you're looking for a no-std version of this template, go here. Contains: a setup script Cargo.toml setup with simulatio

Thor 12 Dec 28, 2021
Yew Tauri Desktop App Template

Yew Tauri Desktop App Template This is Template App for Desktop App. Run Develop $ cargo tauri dev Build App $ cargo tauri build Setup yew setup Using

usa 16 Oct 16, 2022