Crate xtask_wasm

This crate aims to provide an easy and customizable way to help you build Wasm projects by extending them with custom subcommands, based on the xtask concept, instead of using external tooling like wasm-pack.

Minimum Supported Rust Version

This crate requires Rust 1.58.1 at a minimum because there is a security issue on a function we use from std in previous version (see cve-2022-21658).

Setup

The best way to add xtask-wasm to your project is to create a workspace with two packages: your project’s package and the xtask package.

Create a project using xtask

• Create a new directory that will contains the two package of your project and the workspace’s Cargo.toml:

  mkdir my-project
  cd my-project
  touch Cargo.toml
  

• Create the project package and the xtask package using cargo new:

  cargo new my-project
  cargo new xtask
  

• Open the workspace’s Cargo.toml and add the following:

  [workspace]
  default-members = ["my-project"]
  members = [
      "my-project",
      "xtask",
  ]
  

• Create a .cargo/config.toml file and add the following content:

  [alias]
  xtask = "run --package xtask --"
  

The directory layout should look like this:

project
├── .cargo
│   └── config.toml
├── Cargo.toml
├── my-project
│   ├── Cargo.toml
│   └── src
│       └── ...
└── xtask
    ├── Cargo.toml
    └── src
        └── main.rs

And now you can run your xtask package using:

cargo xtask

You can find more informations about xtask here.

Use xtask-wasm as a dependency

Finally, add the following to the xtask package’s Cargo.toml:

[dependencies]
xtask-wasm = "0.1.0"

Usage

This library gives you three structs:

• Dist - Generate a distributed package for Wasm.
• Watch - Re-run a given command when changes are detected (using xtask-watch).
• DevServer - Serve your project at a given IP address.

They all implement clap::Parser allowing them to be added easily to an existing CLI implementation and are flexible enough to be customized for most use-cases.

You can find further information for each type at their documentation level.

Examples

A basic implementation

use std::process::Command;
use xtask_wasm::{anyhow::Result, clap, default_dist_dir};

#[derive(clap::Parser)]
enum Opt {
    Dist(xtask_wasm::Dist),
    Watch(xtask_wasm::Watch),
    Start(xtask_wasm::DevServer),
}


fn main() -> Result<()> {
    let opt: Opt = clap::Parser::parse();

    match opt {
        Opt::Dist(dist) => {
            log::info!("Generating package...");

            dist
                .dist_dir_path("dist")
                .static_dir_path("my-project/static")
                .app_name("my-project")
                .run_in_workspace(true)
                .run("my-project")?;
        }
        Opt::Watch(watch) => {
            log::info!("Watching for changes and check...");

            let mut command = Command::new("cargo");
            command.arg("check");

            watch.run(command)?;
        }
        Opt::Start(mut dev_server) => {
            log::info!("Starting the development server...");

            dev_server.arg("dist").start(default_dist_dir(false))?;
        }
    }

    Ok(())
}

examples/demo

Provides a basic implementation of xtask-wasm to generate the web app package, an “hello world” app using Yew. This example demonstrates a simple directory layout and a customized dist process that use the wasm-opt feature.

The available subcommands are:

• Build the web app package.

  cargo xtask dist
  

  • Build the web app package, download the wasm-opt binary and optimize the Wasm generated by the dist process.

    cargo xtask dist --optimize
    

• Build the web app package and watch for changes in the workspace root.

  cargo xtask watch
  

• Serve an optimized web app dist on 127.0.0.1:8000 and watch for changes in the workspace root.

  cargo xtask start
  

Additional flags can be found using cargo xtask <subcommand> --help.

This example also demonstrates the use of the run-example feature that allows you to use the following:

cargo run --example run_example

This command will run the code in examples/run_example using the development server.

Features

• wasm-opt: enable the WasmOpt struct that helps downloading and using wasm-opt very easily.
• run-example: a helper to run examples from examples/ directory using a development server.
• sass: allow the use of SASS/SCSS in your project.

Troubleshooting

When using the re-export of clap, you might encounter this error:

error[E0433]: failed to resolve: use of undeclared crate or module `clap`
 --> xtask/src/main.rs:4:10
  |
4 | #[derive(Parser)]
  |          ^^^^^^ use of undeclared crate or module `clap`
  |
  = note: this error originates in the derive macro `Parser` (in Nightly builds, run with -Z macro-backtrace for more info)

This occurs because you need to import clap in the scope too. This error can be resolved like this:

use xtask_wasm::clap;

#[derive(clap::Parser)]
struct MyStruct {}

Or like this:

use xtask_wasm::{clap, clap::Parser};

#[derive(Parser)]
struct MyStruct {}

Re-exports

• pub use xtask_watch::anyhow;
• pub use xtask_watch::cargo_metadata;
• pub use xtask_watch::cargo_metadata::camino;
• pub use xtask_watch::clap;
• pub use env_logger;
  run-example
• pub use log;
  run-example
• pub use sass_rs;
  sass

Structs

• DevServer
  A simple HTTP server useful during development.
• Dist
  A helper to generate the distributed package.
• WasmOptwasm-opt
  Helper Abstracting the wasm-opt binary from binaryen for easily optimizing your Wasm binary.
• Watch
  Watches over your project’s source code, relaunching a given command when changes are detected.

Functions

• default_build_command
  Get the default command for the build in the dist process.
• default_dist_dir
  Get the default dist directory.
• metadata
  Fetch the metadata of the crate.
• package
  Fetch information of a package in the current crate.
• xtask_command
  Return a std::process::Command of the xtask command currently running.

Attribute Macros

• run_examplerun-example
  This macro helps to run an example in the project’s examples/ directory using a development server.