Crate xtask_wasm

Expand description

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.

§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",
]
resolver = "2"

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 xtask-wasm to your dependencies:

cargo add -p xtask xtask-wasm

§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 (currently using the 123 version) 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.
Request: Abstraction over an HTTP request.
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.
default_request_handler: Default request handler
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.

Crate xtask_wasmCopy item path