Prerequisites

To run wasm-pack you'll need to have both Rust and npm installed and configured.

In the future, we intend to rewrite the npm registry client bits so that the need for a Node runtime is eliminated. If you're excited about that work- you should reach out to the maintainers and get involved!

Rust

wasm-pack is a Command Line Interface tool written in Rust, and distributed with cargo. As a result, you'll need Rust and cargo to use wasm-pack.

Installing Rust and Cargo

To install Rust, visit this page, which will walk you through installing Rust and cargo on your machine using a tool called rustup.

To confirm you have Rust and cargo installed, run:

rustc --version
cargo --version

Rust Versions

wasm-pack depends on a library called wasm-bindgen. wasm-bindgen requires that you use Rust 1.30.0 or higher. This version is currently only available on the nightly or beta channels.

To get the correct version of Rust, you'll use rustup a Rust version manager that comes bundled with Rust. Run this command to install the latest Rust on the beta channel:

rustup install beta

You can set your project directory to always use this version of Rust by running:

rustup override set beta

npm

Currently, wasm-pack requires that you have npm installed to pack and publish your package. Longterm, this will be replaced by a Rust only version.

If you would rather use another package manager that interfaces with the npm registry you may, however, the pack, publish, and login commands wrap the npm CLI interface and as a result require that npm be installed.

You can install npm by following these instructions.

npm Account

Part of the wasm-pack workflow is to publish your package to the npm Registry.

Regardless of which package manager CLI tool you prefer, if you wish to publish your package to the npm registry you'll need an npm account.

You can find information about signing up for npm here.

If you'd rather not sign up for an account or publish a package to the regsitry, you can use the npm link command to use your generated package locally, which we'll discuss later in the Tutorial.

Project Setup

In this section, how to setup a wasm-pack project.

There are a few things you need to do to setup a project for wasm-pack. We strongly recommending using a template, but you can also set the project up manually.

Using a Template

You can create a new Rust-WebAssembly project by using the rustwasm wasm-pack-template.

To so do, you'll need the cargo-generate tool. To install cargo-generate:

cargo install cargo-generate

Then run:

cargo generate --git https://github.com/rustwasm/wasm-pack-template

You will be prompted to give your project a name. Once you do, you will have a directory with a new project, ready to go. We'll talk about what's been included in this template further in this guide.

Manual Setup

⚠️ This is not the recommended way to start a wasm-pack project! If you ended up here by mistake, go check out our recommended project start, Using A Template.

Step 1: Create a New Rust Library Project

You can create a new Rust project named my-lib using this command.

cargo new --lib my-lib

The --lib flag specifies that the project is a library, which is important because we will be calling this code from JavaScript.

Step 2: Edit your Cargo.toml File

Add the wasm-bindgen dependency

You will need to add wasm-bindgen to your Cargo.toml in the dependencies section. wasm-bindgen is a tool that facilitates interoperability between wasm modules and JavaScript.

⚠️ If you are coming from JavaScript, you might note that when we add the dependency there is no ^ or ~ symbol- it looks like we're locking to the 0.2 version. However, that's not the case! In Rust, the ^ is implied.

Add crate-type

Next, add a [lib] section, with a new field named crate-type set to "cdylib". This specifies that the library is a C compatible dynamic library, which helps cargo pass the correct flags to the Rust compiler when targeting wasm32.

After making these changes, your Cargo.toml file should look something like this:

[package]
name = "hello-wasm"
version = "0.1.0"
authors = ["Ashley Williams <ashley666ashley@gmail.com>"]
description = "babby's first wasm package"
license = "MIT/Apache-2.0"
repository = "https://github.com/ashleygwilliams/hello-wasm"

[lib]
crate-type = ["cdylib"]

[dependencies]
wasm-bindgen="0.2"

Step 3: Write some Rust!

Now that your crate is correctly configured in your Cargo.toml file, the only step left to setup your project is to have some Rust code in your src/lib.rs file.

Browser Example

The template we have gives you a quick "Hello, World" project to use for compiling into a WebAssembly library that you can use in the browser:


# #![allow(unused_variables)]
#fn main() {
extern crate wasm_bindgen;

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
extern {
    fn alert(s: &str);
}

#[wasm_bindgen]
pub fn greet() {
    alert("Hello, World!");
}
#}

And that's it! We'll talk about what this code does in the Tutorial, which you are all setup for now. Happy wasm-packing!

Commands

wasm-pack has several commands to help you during the process of building a Rust-generated WebAssembly project.

  • init: This command has been deprecated in favor of build.
  • build: This command builds a pkg directory for you with compiled wasm and generated JS. Learn more
  • pack and publish: These command will create a tarball, and optionally publish it to a registry, such as npm. Learn more

wasm-pack init (DEPRECATED)

This command has been deprecated in favor of build, which does the same thing, but is a much more representative name for the command. Read the docs for build.

wasm-pack build

The wasm-pack build command creates the files neccessary for JavaScript interoperability and for publishing a package to npm. This involves compiling your code to wasm and generating a pkg folder. This pkg folder will contain the wasm binary, a JS wrapper file, your README, and a package.json file.

Path

The wasm-pack build command can be given an optional path argument, e.g.:

wasm-pack build examples/js-hello-world

This path should point to a directory that contains a Cargo.toml file. If no path is given, the build command will run in the current directory.

Profile

The build command accepts an optional profile argument: one of --dev, --profiling, or --release. If none is supplied, then --release is used.

Th controls whether debug assertions are enabled, debug info is generated, and which (if any) optimizations are enabled.

Profile Debug Assertions Debug Info Optimizations Notes
--dev Yes Yes No Useful for development and debugging.
--profiling No Yes Yes Useful when profiling and investigating performance issues.
--release No No Yes Useful for shipping to production.

The --dev profile will build the output package using cargo's default non-release profile. Building this way is faster but applies few optimizations to the output, and enables debug assertions and other runtime correctness checks. The --profiling and --release profiles use cargo's release profile, but the former enables debug info as well, which helps when investigating performance issues in a profiler.

The exact meaning of the profile flags may evolve as the platform matures.

Target

The build command accepts a --target argument. This will customize the output files to align with a particular type of JS module. This allows wasm-pack to generate either ES6 modules or CommonJS modules for use in browser and in NodeJS. Defaults to browser. The options are:

wasm-pack build --target nodejs
Option Description
nodejs Outputs JS that uses CommonJS modules, for use with a require statement. main key in package.json.
nomodules Outputs JS that use no modules. browser key in package.json.
browser Outputs JS that uses ES6 modules, primarily for use with import statements and/or bundlers such as webpack. module key in package.json. sideEffects: false by default.

Scope

The init command also accepts an optional --scope argument. This will scope your package name, which is useful if your package name might conflict with something in the public registry. For example:

wasm-pack build examples/js-hello-world --scope test

This command would create a package.json file for a package called @test/js-hello-world. For more information about scoping, you can refer to the npm documentation here.

Mode

The build command accepts an optional --mode argument.

wasm-pack build examples/js-hello-world --mode no-install
Option Description
no-install wasm-pack init implicitly and create wasm binding without installing wasm-bindgen.
normal do all the stuffs of no-install with installed wasm-bindgen.

pack and publish

The publish and pack commands interact with the pkg directory that's created when you run wasm-pack init. The pack command creates a tarball from the pkg directory and the publish command creates a tarball from the pkg directory and publishes it to the NPM registry.

Underneath, these commands use npm pack and npm publish. You can read more about these in the NPM documentation:

Both these commands take the path to the pkg directory as the first argument. You can either set the argument directly to the pkg directory or to the parent of the pkg directory:

$ wasm-pack pack myproject/pkg
| 🎒  packed up your package!
$ wasm-pack pack myproject
| 🎒  packed up your package!

If you try to call pack or publish on another directory, you get an error:

$ wasm-pack pack myproject/src/
Unable to find the pkg directory at path 'myproject/src/', or in a child directory of 'myproject/src/'

If you don't set a path, they use the current directory as the path.

Tutorial

The goal of this tutorial is to introduce you to the wasm-pack workflow.

This tutorial is aimed at folks who are both beginners to WebAssembly and Rust- you don't need much Rust knowledge to complete this tutorial.

Be sure to have done the following before starting:

  1. Install wasm-pack

  2. Read and install the Prerequisites.

    • You'll need Rust, version 1.30 or higher. (Currently either beta or nightly channels). Learn more.
    • You'll need Node.js and npm installed. You'll also need an npm Account. Learn more.

⚠️ We strongly recommend that you install Node.js using a version manager. You can learn more here.

Getting Started

You can create a new Rust-WebAssembly project by using the rustwasm wasm-pack-template.

To so do, you'll need the cargo-generate tool. To install cargo-generate:

cargo install cargo-generate

Then run:

cargo generate --git https://github.com/rustwasm/wasm-pack-template

You will be prompted to give your project a name. Once you do, you will have a directory with a new project, ready to go. We'll talk about what's been included in this template further in this guide.

Manual Setup

⚠️ If you'd rather not use a template, or are having trouble with the template, you can do a manual setup by following these instructions.

Template Deep Dive

⚠️ This section is a deep dive into the contents of the files of a "Hello, World" project, specifically written for people who are not that familiar with Rust. If you'd rather just checkout the workflow, feel free to skip this section!

⚠️ If you haven't used a template to set up your project, the contents of your files may look slightly different than what is described here.

What the Template Gave Us

Let's start by taking a look at what the template generated for us.

Cargo.toml

Cargo.toml is the manifest file for Rust's package manager, cargo. This file contains metadata such as name, version, and dependencies for packages, which are call "crates" in Rust.

There's a bunch of metadata that the template gives us, but there are 3 key parts to discuss:


1. crate-type

[lib]
crate-type = ["cdylib"]

A Rust-wasm crate is a bit different from a normal crate, and as a result, we need to note this in our Cargo.toml.

When cargo is told to build a project, or compilation is otherwise done on a Rust project, the Rust compiler will need to link crates together, using a particular method, either staticly or dynamically. The two types of crate that you are likely most familiar with are #[crate_type = "bin"] and #[crate_type = "lib"], which are the crate types that largely represent the difference between Rust application projects and Rust libraries.

#[crate_type = "cdylib"] signifies that you'd like the compiler to create a dynamic system library. This type of library is suited for situations where you'd like to compile Rust code as a dynamic library to be loaded from another language. In our case, we'll be compiling to a .wasm file, but this output type will create *.so files on Linux, *.dylib files on macOS, and *.dll files on Windows in non-wasm circumstances.

You can read more about linking and crate types, here.

2. wasm-bindgen dependency

wasm-bindgen is our most important dependency. This package allows us to use the #[wasm-bindgen] attribute to tag code that represents the interface we want between our JavaScript and Rust-generated wasm. We can import JS and export Rust by using this attribute.

wasm-bindgen = "0.2"

We'll see more about how to use this library when we discuss what has been generated in lib.rs.

⚠️ If you are coming from JavaScript, you might note that when we add the dependency there is no ^ or ~ symbol- it looks like we're locking to the 0.2 version. However, that's not the case! In Rust, the ^ is implied.

3. [features] and wee-alloc, console-error-panic-hook dependencies

As part of our effort to design a template that helps people discover useful crates for their particular use case, this template includes 2 dependencies that can be very useful for folks developing Rust-wasm crates: console-error-panic-hook and wee-alloc.

Because these dependencies are useful primarily in a specifc portion of the Rust-wasm crate development workflow, we've also set up a bit of glue code that allows us to include them both as dependences, but allowing for them to be optionally included.

[features]
default-features = ["console_error_panic_hook", "wee_alloc"]

[dependencies]
cfg-if = "0.1.2"

# The `console_error_panic_hook` crate provides better debugging of panics by
# logging them with `console.error`. This is great for development, but requires
# all the `std::fmt` and `std::panicking` infrastructure, so isn't great for
# code size when deploying.
console_error_panic_hook = { version = "0.1.1", optional = true }

# `wee_alloc` is a tiny allocator for wasm that is only ~1K in code size
# compared to the default allocator's ~10K. It is slower than the default
# allocator, however.
wee_alloc = { version = "0.4.1", optional = true }

[cfg-if] allows us to check if certain features are enabled on a rust crate. We'll use this crate in utils.rs to optionally enable console_error_panic_hook or wee_alloc. By default, we have them enabled. To disable them, we can remove their entry from the default-features vector.

To learn more about these features, we discuss them in depth in the utils.rs section.

src/lib.rs

🚧 COMING SOON 🚧

src/utils.rs

🚧 COMING SOON 🚧

Package Code for npm

We've made our code so now we need to package it all up. In your project directory run the following command:

$ wasm-pack build --scope MYSCOPE

where MYSCOPE is your npm username. Normally you could just type wasm-pack init but since other people are doing this tutorial as well we don't want conflicts with the wasm-add package name! This command when run does a few things:

  1. It'll compile your code to wasm if you haven't already
  2. It'll generate a pkg folder with the wasm file, a JS wrapper file around the wasm, your README, and a package.json file.

This is everything you need to upload your code to npm! Let's do just that!

First off you'll need to login to npm with the account you made earlier if you didn't already have one:

$ wasm-pack login

Next you'll need to go into the pkg directory and actually upload the package:

$ cd pkg
$ npm publish --access=public

Now normally if things are not scoped you can just do npm publish but if you give it a scope you'll need to tell npm that this is actually public so it can publish it. We need to do that here since we gave our packages a scope to avoid conflicting with each other! Next up is actually running the code and verifying we got it from npm and how we can use that code.

Run The Code From npm

This portion of the tutorial will help you create a Webpack JavaScript project that will run your WebAssembly code in the browser.

Scaffold a JavaScript Project

To scaffold a project that we can use our new package in, we'll use an npm template called create-wasm-app. To use this run this command in a directory different than your Rust project:

npm init wasm-app

This tool will ask you for the name of a project, and then create a directory with that name.

If we look in that directory, we'll see the following:

  • .gitignore: ignores node_modules
  • LICENSE-APACHE and LICENSE-MIT: most Rust projects are licensed this way, so these are included for you
  • README.md: the file you are reading now!
  • index.html: a bare bones html document that includes the webpack bundle
  • index.js: example js file with a comment showing how to import and use a wasm pkg
  • package.json and package-lock.json:
  • webpack.config.js: configuration file for bundling your js with webpack

Add Your npm Package

The scaffolded project includes an example WebAssembly package, hello-wasm-pack, in your package.json. Go into the package.json file, add your package, and remove the hello-wasm-pack dependency from the "dependencies" section.

Now, open up the index.js file. Replace the hello-wasm-pack in the first line with the name of your package:

import * as wasm from "<your package name>";

wasm.greet();

Run The Project

Before we run our project, we need to make sure we install our dependencies:

npm install

We should be ready to run our project now! To run our project we'll run:

npm start

Then in a web browser navigate to http://localhost:8080 and you should be greeted with an alert box that says "Hello World!".

If you did congrats you've successfully uploaded your first bit of wasm code to npm and used it properly!

Cargo.toml Configuration

wasm-pack can be configured via the package.metadata.wasm-pack key in Cargo.toml. Every option has a default, and is not required.

There are three profiles: dev, profiling, and release. These correspond to the --dev, --profiling, and --release flags passed to wasm-pack build.

The available configuration options and their default values are shown below:

[package.metadata.wasm-pack.profile.dev.wasm-bindgen]
# Should we enable wasm-bindgen's debug assertions in its generated JS glue?
debug-js-glue = true
# Should wasm-bindgen demangle the symbols in the "name" custom section?
demangle-name-section = true
# Should we emit the DWARF debug info custom sections?
dwarf-debug-info = false

[package.metadata.wasm-pack.profile.profiling.wasm-bindgen]
debug-js-glue = false
demangle-name-section = true
dwarf-debug-info = false

[package.metadata.wasm-pack.profile.release.wasm-bindgen]
debug-js-glue = false
demangle-name-section = true
dwarf-debug-info = false

Contributing

Prerequisites

The technical prerequisites for contributing to this project are the same as for using it. You can find them documented here.

You'll also want to check out the contributing guidelines.

🏃‍♀️ Up and Running

  1. fork and clone this repository
  2. install [node/npm]
  3. cd wasm-pack
  4. cargo run. To test command line arguments you can run cargo run -- <args>.

Documentation

Documentation lives in the /docs directory. Each command has it's own page. Additionally there are extra pages explaining the prerequisites, setup, and how to contribute (which you are reading now!).

Tests

Tests live in the /tests directory. To run the tests you can run:

cargo  test

You can also manually test the CLI tool by running:

cargo run -- <args>

...for example:

cargo run -- init /tests/fixtures/js-hello-world --scope=ag_dubs