refactor!: overhaul DevServer and Dist APIs, add Hook and Transformer traits

CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `DevServer::xtask(name)` and `DevServer::cargo(subcommand)` convenience
+  builders for setting the main watch command. These replace the old implicit
+  behavior where `arg()` would silently create an xtask command if none was set.
+- `DevServer::arg()`, `DevServer::args()`, `DevServer::env()`,
+  `DevServer::envs()` restored as builder methods on `DevServer` for passing
+  extra arguments/environment to the `xtask()` and `cargo()` shorthands (which
+  build the command internally). These now panic with a clear message if called
+  before a command is set — a programmer error, not a runtime condition.
+- `DevServer::dist_dir(path)` builder to explicitly set the directory served by
+  the dev server (previously had to be passed to `start()`).
+- `Hook` trait for `DevServer` pre/post commands. Lets you construct a
+  `process::Command` with access to the final server configuration (e.g.
+  resolved `port`, `dist_dir`). A blanket impl is provided for
+  `process::Command` itself.
+- `Transformer` trait for `Dist` asset processing. Transformers are tried in
+  order per file; the first to return `Ok(true)` claims the file, unclaimed
+  files are plain-copied. Errors are propagated immediately via `?`.
+- `Dist::transformer(impl Transformer)` builder to register asset transformers.
+- `SassTransformer` struct (behind the `sass` feature) implementing `Transformer`
+  to compile SASS/SCSS files to CSS.
+- `Dist::optimize_wasm(WasmOpt)` builder (behind the `wasm-opt` feature) to
+  integrate wasm-opt directly into the `build()` pipeline. Automatically skipped
+  for debug builds.
+- `Dist::default_debug_dir()` and `Dist::default_release_dir()` associated
+  functions returning `camino::Utf8PathBuf`.
+- "Why xtask-wasm?" section added to the README and crate-level documentation.
+
+### Changed
+
+- **BREAKING** `DevServer::start()` no longer takes a `dist_dir` path argument.
+  The directory is inferred from `Dist::default_debug_dir()` or set via the new
+  `DevServer::dist_dir()` builder.
+- **BREAKING** `DevServer::command()` now accepts a `process::Command` instead
+  of a program name string, consistent with `pre()` and `post()`.
+- **BREAKING** `DevServer::not_found()` renamed to `DevServer::not_found_path()`.
+- **BREAKING** `Dist::run()` renamed to `Dist::build()`.
+- **BREAKING** `Dist::dist_dir_path()` renamed to `Dist::dist_dir()`.
+- **BREAKING** `Dist::static_dir_path()` renamed to `Dist::assets_dir()`. The
+  assets directory is now auto-discovered at `<package_root>/assets` when not
+  explicitly set. The copy step is silently skipped (with a `log::debug!`) if
+  the directory does not exist, allowing users with custom asset pipelines to
+  call `build()` without a pre-existing assets directory on disk.
+- **BREAKING** `run_in_workspace` field and `use_workspace_root()` /
+  `use_current_dir()` methods removed from `Dist`. The build command always runs
+  from the workspace root, which was the correct value in virtually all
+  use-cases. The `false` branch was unreliable anyway since Cargo crate
+  resolution requires being inside the workspace.
+- **BREAKING** `SassTransformer` is now opt-in. Previously `Dist::default()`
+  would auto-seed a `SassTransformer` when the `sass` feature was enabled,
+  meaning any user adding their own `SassTransformer` would silently end up with
+  two in the pipeline. Use `.transformer(SassTransformer::default())` to opt in.
+- **BREAKING** `Request::dist_dir_path` field renamed to `Request::dist_dir`.
+- `Dist::default_debug_dir()` and `Dist::default_release_dir()` now return an
+  owned `camino::Utf8PathBuf` instead of `&'static camino::Utf8Path`, removing
+  the `lazy_static` machinery and the `.as_std_path().to_path_buf()` boilerplate
+  at call sites.
+- `walkdir` promoted from a `sass`-feature-gated dependency to a regular
+  dependency (used unconditionally by `copy_assets`).
+- `cfg_not_wasm32!` / `cfg_wasm32!` / `cfg_sass!` / `cfg_wasm_opt!` /
+  `cfg_run_example!` macros removed. These wrapped `mod` declarations inside
+  macro bodies, making those modules invisible to `cargo fmt` and silently
+  skipping format checks on the bulk of the codebase. Replaced with plain
+  `#[cfg(...)]` attributes.
+- MSRV bumped to 1.88.
+- `run_example` macro: `static_dir` argument renamed to `assets_dir`.
+- `run_example` macro: default `index.html` is no longer generated when
+  `app_name` is set. The default template hardcodes `app.js`/`app_bg.wasm`;
+  with a custom app name those filenames are wrong. Users setting `app_name`
+  should provide their own `index.html` via the `index` argument or in their
+  assets directory.
+
+### Removed
+
+- **BREAKING** Free functions `default_dist_dir(release: bool)`,
+  `default_dist_dir_debug()`, and `default_dist_dir_release()` removed in favor
+  of `Dist::default_debug_dir()` and `Dist::default_release_dir()`.
+- **BREAKING** `Dist::sass_options()` removed. Configure SASS compilation
+  options via `SassTransformer { options: ... }` passed to `Dist::transformer()`.
+
+### Fixed
+
+- `SassTransformer`: SASS compilation errors are now propagated as `Err` instead
+  of panicking.
+- `copy_assets`: transformer errors are now propagated immediately. The previous
+  iterator chain used `find()` with `map_or(false, ...)` which treated `Err` as
+  `false` and silently fell through to the plain-copy fallback.
+- Auto-discovery was looking for a `public/` directory while the rest of the
+  codebase used `assets`, silently breaking auto-discovery for anyone following
+  the documented naming convention.
+
+[Unreleased]: https://github.com/rustminded/xtask-wasm/compare/v0.5.3...HEAD

Cargo.toml

@@ -7,15 +7,15 @@ description = "Customizable subcommands to build your Wasm projects using xtask.
 homepage = "https://github.com/rustminded/xtask-wasm"
 repository = "https://github.com/rustminded/xtask-wasm"
 documentation = "https://docs.rs/xtask-wasm"
-rust-version = "1.82"
+rust-version = "1.88"
 readme = "README.md"
 categories = ["development-tools::build-utils"]
 keywords = ["wasm", "cli"]
-include = ["src/**/*.rs", "README.md", "LICENSE.Apache-2.0", "LICENSE.MIT"]
+include = ["src/**/*.rs", "README.md", "CHANGELOG.md", "LICENSE.Apache-2.0", "LICENSE.MIT"]
 
 [features]
 run-example = ["xtask-wasm-run-example", "console_error_panic_hook", "wasm-bindgen", "env_logger"]
-sass = ["sass-rs", "walkdir"]
+sass = ["sass-rs"]
 wasm-opt = ["binary-install"]
 
 [dependencies]
@@ -33,7 +33,7 @@ fs_extra = "1.2.0"
 lazy_static = "1.4.0"
 log = "0.4.14"
 sass-rs = { version = "0.2.2", optional = true }
-walkdir = { version = "2.3.2", optional = true }
+walkdir = "2.3.2"
 # NOTE: we don't depend on this crate but we need to activate this feature otherwise it's super slow
 walrus = { version = "0.23.0", features = ["parallel"] }
 wasm-bindgen-cli-support = "0.2.100"
@@ -42,6 +42,9 @@ xtask-watch = "0.3.2"
 [target.'cfg(unix)'.dependencies]
 libc = "0.2.112"
 
+[dev-dependencies]
+env_logger = { version = "0.11.6" }
+
 [package.metadata.docs.rs]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]

README.md

@@ -16,13 +16,51 @@
 [deps-url]: https://deps.rs/repo/github/rustminded/xtask-wasm
 [licenses-badge]: https://img.shields.io/crates/l/xtask-wasm
 
+**[Changelog](CHANGELOG.md)**
+
 <!-- cargo-rdme start -->
 
 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](https://github.com/matklad/cargo-xtask/), instead of using
 external tooling like [`wasm-pack`](https://github.com/rustwasm/wasm-pack).
 
+**[Changelog](https://github.com/rustminded/xtask-wasm/blob/main/CHANGELOG.md)**
+
+## Why xtask-wasm?
+
+### No external tools to install
+
+`wasm-pack` and `trunk` are separate binaries that must be installed outside
+of Cargo — via `cargo install`, a shell script, or a system package manager.
+This means every contributor and every CI machine needs an extra installation
+step, and there is no built-in guarantee that everyone is running the same
+version.
+
+With xtask-wasm, `cargo xtask` is all you need. The build tooling is a
+regular Cargo dependency, versioned in your `Cargo.lock` and reproduced
+exactly like every other dependency in your project.
+
+### `wasm-bindgen` version is always in sync
+
+This is the most common source of pain with `wasm-pack` and `trunk`: the
+`wasm-bindgen` CLI tool version must exactly match the `wasm-bindgen` library
+version declared in your `Cargo.toml`. When they drift — after a `cargo
+update`, a fresh clone, or a CI cache invalidation — you get a cryptic error
+at runtime rather than a clear compile-time failure.
+
+xtask-wasm uses [`wasm-bindgen-cli-support`](https://crates.io/crates/wasm-bindgen-cli-support)
+as a library dependency. The version is pinned in your `Cargo.lock` alongside
+your `wasm-bindgen` library dependency and kept in sync automatically — no
+manual version matching required.
+
+### Fully customizable
+
+Because the build process is plain Rust code living inside your workspace,
+you can extend, replace or wrap any step. `wasm-pack` and `trunk` are
+opaque binaries driven by configuration files; xtask-wasm gives you the full
+build logic as code, under your control.
+
 ## Setup
 
 The best way to add xtask-wasm to your project is to create a workspace
@@ -113,6 +151,22 @@ They all implement [`clap::Parser`](https://docs.rs/clap/latest/clap/trait.Parse
 allowing them to be added easily to an existing CLI implementation and are
 flexible enough to be customized for most use-cases.
 
+The pre and post hooks of [`DevServer`](https://docs.rs/xtask-wasm/latest/xtask_wasm/struct.DevServer.html)
+accept any type implementing the
+[`Hook`](https://docs.rs/xtask-wasm/latest/xtask_wasm/trait.Hook.html) trait.
+This lets you construct a [`process::Command`](https://doc.rust-lang.org/std/process/struct.Command.html) based on the server's final configuration
+— for example, to pass the resolved `dist_dir` or `port` as arguments to an external tool.
+A blanket implementation is provided for [`process::Command`](https://doc.rust-lang.org/std/process/struct.Command.html) itself, so no changes are
+needed for simple use-cases.
+
+Asset files copied by [`Dist`](https://docs.rs/xtask-wasm/latest/xtask_wasm/struct.Dist.html)
+can be processed by types implementing the
+[`Transformer`](https://docs.rs/xtask-wasm/latest/xtask_wasm/trait.Transformer.html) trait.
+Transformers are tried in order for each file; the first to return `Ok(true)` claims the file,
+while unclaimed files are copied verbatim. When the `sass` feature is enabled,
+[`SassTransformer`](https://docs.rs/xtask-wasm/latest/xtask_wasm/struct.SassTransformer.html)
+is available to compile SASS/SCSS files to CSS.
+
 You can find further information for each type at their documentation level.
 
 ## Examples
@@ -121,7 +175,7 @@ You can find further information for each type at their documentation level.
 
 ```rust
 use std::process::Command;
-use xtask_wasm::{anyhow::Result, clap, default_dist_dir};
+use xtask_wasm::{anyhow::Result, clap};
 
 #[derive(clap::Parser)]
 enum Opt {
@@ -132,18 +186,20 @@ enum Opt {
 
 
 fn main() -> Result<()> {
+    env_logger::builder()
+        .filter_level(log::LevelFilter::Info)
+        .init();
+
     let opt: Opt = clap::Parser::parse();
 
     match opt {
         Opt::Dist(dist) => {
             log::info!("Generating package...");
 
             dist
-                .dist_dir_path(default_dist_dir(false))
-                .static_dir_path("my-project/static")
+                .assets_dir("my-project/assets")
                 .app_name("my-project")
-                .run_in_workspace(true)
-                .run("my-project")?;
+                .build("my-project")?;
         }
         Opt::Watch(watch) => {
             log::info!("Watching for changes and check...");
@@ -156,36 +212,34 @@ fn main() -> Result<()> {
         Opt::Start(dev_server) => {
             log::info!("Starting the development server...");
 
-            dev_server.arg("dist").start(default_dist_dir(false))?;
+            dev_server
+                .xtask("dist")
+                .start()?;
         }
     }
 
     Ok(())
 }
 ```
 
+Note: this basic implementation uses `env_logger` and `log`. Add them to the `Cargo.toml` of
+your `xtask` (or use your preferred logger).
+
 ### [`examples/demo`](https://github.com/rustminded/xtask-wasm/tree/main/examples/demo)
 
 Provides a basic implementation of xtask-wasm to generate the web app
 package, an "hello world" app using [Yew](https://yew.rs/). This example
-demonstrates a simple directory layout and a customized dist process
-that use the `wasm-opt` feature.
+demonstrates a simple directory layout and a dist process that uses the
+`wasm-opt` feature via [`Dist::optimize_wasm`](https://docs.rs/xtask-wasm/latest/xtask_wasm/struct.Dist.html#method.optimize_wasm).
 
 The available subcommands are:
 
-* Build the web app package.
+* Build and optimize the web app package (downloads
+  [`wasm-opt`](https://github.com/WebAssembly/binaryen#tools) if not cached).
 
   ```console
   cargo xtask dist
   ```
-  * Build the web app package, download the
-    [`wasm-opt`](https://github.com/WebAssembly/binaryen#tools)
-    binary (currently using the 123 version) and optimize the Wasm generated by the dist
-    process.
-
-    ```console
-    cargo xtask dist --optimize
-    ```
 
 * Build the web app package and watch for changes in the workspace root.
 
@@ -214,12 +268,22 @@ This command will run the code in `examples/run_example` using the development s
 ## Features
 
 * `wasm-opt`: enable the
-   [`WasmOpt`](https://docs.rs/xtask-wasm/latest/xtask_wasm/struct.WasmOpt.html) struct that helps
-   downloading and using [`wasm-opt`](https://github.com/WebAssembly/binaryen#tools) very
-   easily.
+  [`WasmOpt`](https://docs.rs/xtask-wasm/latest/xtask_wasm/struct.WasmOpt.html) struct and
+  [`Dist::optimize_wasm`](https://docs.rs/xtask-wasm/latest/xtask_wasm/struct.Dist.html#method.optimize_wasm)
+  for downloading and running [`wasm-opt`](https://github.com/WebAssembly/binaryen#tools)
+  automatically as part of the dist build. This is the recommended way to integrate wasm-opt —
+  no custom wrapper struct or manual path computation needed:
+
+  ```rust
+  // requires the `wasm-opt` feature
+  dist.optimize_wasm(WasmOpt::level(1).shrink(2))
+      .build("my-project")?;
+  ```
+
 * `run-example`: a helper to run examples from `examples/` directory using a development
-   server.
-* `sass`: allow the use of SASS/SCSS in your project.
+  server.
+* `sass`: enable SASS/SCSS compilation via [`SassTransformer`](https://docs.rs/xtask-wasm/latest/xtask_wasm/struct.SassTransformer.html).
+  Add it to your [`Dist`](https://docs.rs/xtask-wasm/latest/xtask_wasm/struct.Dist.html) with `.transformer(SassTransformer::default())`.
 
 ## Troubleshooting
 

examples/demo/webapp/examples/run_example.rs

@@ -6,7 +6,7 @@ extern "C" {
     fn log(message: &str);
 }
 
-#[xtask_wasm::run_example(static_dir = "webapp/static", app_name = "web_app")]
+#[xtask_wasm::run_example(app_name = "web_app")]
 fn run_app() {
     log("Hello World!");
 }

examples/demo/xtask/src/main.rs

@@ -11,21 +11,11 @@ struct Opt {
 
 #[derive(clap::Parser)]
 enum Command {
-    Dist(Build),
+    Dist(xtask_wasm::Dist),
     Watch(xtask_wasm::Watch),
     Start(xtask_wasm::DevServer),
 }
 
-#[derive(clap::Parser)]
-struct Build {
-    /// Optimize the generated package using `wasm-opt`.
-    #[clap(long)]
-    optimize: bool,
-
-    #[clap(flatten)]
-    base: xtask_wasm::Dist,
-}
-
 fn main() -> Result<()> {
     let opt: Opt = clap::Parser::parse();
 
@@ -34,20 +24,13 @@ fn main() -> Result<()> {
         .init();
 
     match opt.cmd {
-        Command::Dist(arg) => {
+        Command::Dist(dist) => {
             log::info!("Generating package...");
 
-            let dist_result = arg
-                .base
-                .static_dir_path("webapp/static")
+            dist.assets_dir("webapp/assets")
                 .app_name("web_app")
-                .run("webapp")?;
-
-            if arg.optimize {
-                xtask_wasm::WasmOpt::level(1)
-                    .shrink(2)
-                    .optimize(dist_result.join("web_app.wasm"))?;
-            }
+                .optimize_wasm(xtask_wasm::WasmOpt::level(1).shrink(2))
+                .build("webapp")?;
         }
         Command::Watch(arg) => {
             log::info!("Watching for changes and check...");
@@ -60,7 +43,7 @@ fn main() -> Result<()> {
         Command::Start(arg) => {
             log::info!("Starting the development server...");
 
-            arg.arg("dist").start(xtask_wasm::default_dist_dir(false))?;
+            arg.xtask("dist").start()?;
         }
     }