A cargo subcommand for the client-side Web
This cargo subcommand aims to make it easy and convenient to build, develop and deploy client-side Web applications written in Rust.
This software was brought to you thanks to these wonderful people:
- Daniel Norman
- Anselm Eickhoff
- Edward Knyshov
- Ferran Pujol Camins
- Johan Andersson
- Stephen Sugden
Currently it supports the following features:
cargo web build- will build your project using one of Rust's three Web backends:
cargo web test- will run your tests either under:
- Under a headless instance of Google Chrome (default)
- Under Node.js (when you pass
cargo web start- will build your project, start an embedded webserver and will continuously rebuild it if necessary; supports automatic reloading with
cargo web deploy- will build your project and emit all of the necessary files so that you can easily serve them statically.
- Will automatically download and install Emscripten for you (if necessary) on the following platforms:
- Linux x86-64
- Linux x86
- Will automatically garbage-collect your WebAssembly artifacts.
It's also highly recommended that you check out the stdweb crate if you want
is what makes it possible to use
js! macro on Rust's native WebAssembly
$ cargo install cargo-web
$ cargo install --force cargo-web
Or clone and build with
$ cargo build --release then place in your $PATH.
On Linux the installation can fail with a message that it can't find OpenSSL,
in which case you most likely need to install the
-dev package for OpenSSL
from your distribution's repositories. (On Ubuntu it's called
cargo-web has its own configuration file which you can put next to
Here's an example configuration showing every supported key:
If you use any external crates which have a
will load it and use it.
A few restrictions concerning the
- You can't have overlapping
prepend-jskeys. You can either define a single global
prepend-js, or multiple per-target ones.
link-argscurrently can't have any spaces in them.
- The order in which
cargo-webwill process the
Web.tomlfiles from multiple crates is deterministic yet unspecified. This means that you shouldn't depend on this order in any way.
Any static files you'd like to have served when running
cargo web start or deployed
cargo web deploy can be put in a directory called
static in the root
of your crate. No static artifacts are required by default; an
index.html file will
be automatically generated for you if it's missing. You can, of course, put your own
file, in which case it will be used instead of the autogenerated one.
cargo-web during compilation
If during compilation you'd like to detect that your project is being built with
you can check the
COMPILING_UNDER_CARGO_WEB environment variable, which will be set to
cargo-web on Travis
You can use the following script to download and install the latest
CARGO_WEB_RELEASE=$(curl -L -s -H 'Accept: application/json' https://github.com/koute/cargo-web/releases/latest) CARGO_WEB_VERSION=$(echo $CARGO_WEB_RELEASE | sed -e 's/.*"tag_name":"\([^"]*\)".*/\1/') CARGO_WEB_URL="https://github.com/koute/cargo-web/releases/download/$CARGO_WEB_VERSION/cargo-web-x86_64-unknown-linux-gnu.gz" echo "Downloading cargo-web from: $CARGO_WEB_URL" curl -L $CARGO_WEB_URL | gzip -d > cargo-web chmod +x cargo-web mkdir -p ~/.cargo/bin mv cargo-web ~/.cargo/bin
Running tests under headless Chrome
cargo web test will run your tests under headless Chrome. To be able to use this on Travis
you need to add something like this to your
addons: chrome: stable
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.