Build, bundle & ship your Rust WASM application to the web

”Pack your things, we’re going on an adventure!”
~ Ferris

Star
Discord Chat Number of downloads
Explore More ⇩
Getting Started
- Install
- Additional tools
- App Setup
- JavaScript interoperability
Next Steps
Contributing
License
Overview

Trunk NG is a WASM web application bundler for Rust. Trunk uses a simple, optional-config pattern for building & bundling WASM, JS snippets & other assets (images, css, scss) via a source HTML file.

NOTE: Trunk NG is a fork of Trunk, adding some fixes and enhancements. Read more about it here.

Getting Started

Install

First, install Trunk via one of the following options.

Plain cargo

Download the sources and build them yourself:

cargo install --locked trunk-ng

Cargo binstall

You can download a released binary from GitHub releases through binstall.

cargo binstall trunk-ng

GitHub release download

Fetch and unpack a released binary from the release page.

For example (be sure to check for the most recent version):

wget -qO- https://github.com/ctron/trunk/releases/download/0.17.10/trunk-ng-x86_64-unknown-linux-gnu.tar.gz | tar -xzf-

NixOS

Note: trunk-ng is currently in the unstable channel. It should be part of the next release.

nix-env -i trunk-ng

Brew

Note: Brew isn't supported at the moment. There is a PR pending, however it seems to publishing a fork of something without acknowledging it's a fork isn't something that Homebrew does: https://github.com/Homebrew/homebrew-core/pull/150913

brew install trunk-ng

Additional tools

Any additional tools like wasm-bindgen and wasm-opt are automatically downloaded and managed by trunk. Therefore, no further steps required 🎉.

Note: Until wasm-bindgen has pre-built binaries for Apple M1, M1 users will need to install wasm-bindgen manually.

cargo install --locked wasm-bindgen-cli

App Setup

Get setup with your favorite wasm-bindgen based framework. Yew & Seed are the most popular options today, but there are others. Trunk will work with any wasm-bindgen based framework. The easiest way to ensure that your application launches properly is to setup your app as an executable with a standard main function:

fn main() {
    // ... your app setup code here ...
}

Trunk uses a source HTML file to drive all asset building and bundling. Trunk also uses the official dart-sass, so let's get started with the following example. Copy this HTML to the root of your project's repo as index.html:

<html>
  <head>
    <link data-trunk rel="scss" href="path/to/index.scss"/>
  </head>
</html>

trunk-ng build will produce the following HTML at dist/index.html, along with the compiled scss, WASM & the JS loader for the WASM:

<html>
  <head>
    <link rel="stylesheet" href="/index-c920ca43256fdcb9.css">
    <link rel="preload" href="/index-7eeee8fa37b7636a_bg.wasm" as="fetch" type="application/wasm" crossorigin="">
    <link rel="modulepreload" href="/index-7eeee8fa37b7636a.js">
  </head>
  <body>
    <script type="module">
      import init, * as bindings from '/index-7eeee8fa37b7636a.js';
      window.wasmBindings = bindings;
      init('/index-7eeee8fa37b7636a_bg.wasm');
    </script>
  </body>
</html>

The contents of your dist dir are now ready to be served on the web.

JavaScript interoperability

Trunk will create the necessary JavaScript code to bootstrap and run the WebAssembly based application. It will also include all JavaScript snippets generated by wasm-bindgen for interfacing with JavaScript functionality.

By default, functions exported from Rust, using wasm-bingen, can be accessed in the JavaScript code through the global variable window.wasmBindings. This behavior can be disabled, and the name can be customized.

Next Steps

That's not all! Trunk has even more useful features. Head on over to the following sections to learn more about how to use Trunk effectively.

Contributing

Anyone and everyone is welcome to contribute! Please review the CONTRIBUTING.md document for more details. The best way to get started is to find an open issue, and then start hacking on implementing it. Letting other folks know that you are working on it, and sharing progress is a great approach. Open pull requests early and often, and please use GitHub's draft pull request feature.

License

trunk-ng (as well as trunk) is licensed under the terms of the MIT License or the Apache License 2.0, at your choosing.