How to Automate Tasks in the Brush Project: Complete Script Guide

The Brush repository provides npm scripts and Python utilities that automate building WebAssembly modules, running development servers, and generating benchmark data without manually invoking underlying toolchains.

The Brush project, hosted at ArthurBrussee/brush, streamlines Gaussian splatting workflows through a unified set of automation scripts defined across workspace package.json files. These scripts handle the complex orchestration between Rust, WebAssembly, and Node.js toolchains, while a Python helper supports benchmark automation. Whether you are developing the core library or deploying the web interface, these automation hooks in the root package.json and application directories serve as the canonical entry points for all routine tasks.

Development Server Automation

The repository provides distinct development environments for the main application and the JavaScript library bindings. These scripts abstract the Vite configuration and Wasm initialization into single commands.

Starting the Web Interface

To launch the brush-app web interface with hot-reloading, run npm run dev from the repository root. This command delegates to apps/brush-app/web/package.json, starting a Vite development server typically accessible at http://localhost:5173. The root package.json also exposes npm run dev:app as an explicit shortcut to this same endpoint.

# Start the brush-app development server

npm run dev

Building the JavaScript Library

For developers working on the brush-js JavaScript bindings specifically, the root package.json defines npm run dev:lib. This command targets apps/brush-js/web/package.json to initialize the library development environment separately from the main application frontend.

# Start development mode for the brush-js library

npm run dev:lib

Production Build Automation

Production builds require compiling Rust code to WebAssembly before bundling with Vite. The automation scripts handle both development and release optimizations through distinct build paths.

WebAssembly Compilation Modes

The apps/brush-app/web/package.json defines granular Wasm build commands using wasm-pack. Use npm run build:wasm-dev to compile with --dev flags for faster iteration during development, or npm run build:wasm-release to compile with --release flags for optimized runtime performance.

# Development build (faster compilation, slower runtime)

npm run build:wasm-dev

# Production build (slower compilation, optimized output)

npm run build:wasm-release

Full Production Bundling

The npm run build:app command chains the Wasm compilation with vite build to produce the complete static site. The root-level npm run build provides a convenience wrapper that invokes build:app and manages workspace dependencies. After building, use npm run preview to serve the ./dist/ folder locally using vite preview for final verification.

# Build the complete production bundle (Wasm + Vite)

npm run build

# Preview the production build locally

npm run preview

Benchmark Data Generation

The benchmark suite relies on reference data generated via crates/brush-bench-test/test_cases/generate_reference.py. This Python script processes synthetic scenes, executes forward passes through the rendering pipeline, and persists outputs as .safetensors files for regression testing.

# Generate reference data for benchmark tests

python crates/brush-bench-test/test_cases/generate_reference.py

Continuous Integration

The GitHub Actions workflow in .github/workflows/ci.yml validates these automation scripts by executing npm ci, npm run build, and Cargo tests. This ensures every commit maintains build integrity across the Rust and JavaScript boundaries, confirming that the npm scripts remain the authoritative method for automating tasks in the Brush project.

# The CI workflow runs these same commands automatically

npm ci
npm run build
cargo test

Summary

• Use npm run dev in the root directory to start hot-reloading development servers for web applications via apps/brush-app/web/package.json.
• Compile WebAssembly in development mode with npm run build:wasm-dev or release mode with npm run build:wasm-release as defined in the app-specific package files.
• Generate production bundles using npm run build, which orchestrates both Wasm compilation and Vite bundling into the ./dist/ folder.
• Create benchmark reference data by executing python crates/brush-bench-test/test_cases/generate_reference.py.
• Trust the CI pipeline in .github/workflows/ci.yml to validate all automation paths on every commit using the same npm scripts.

Frequently Asked Questions

What is the difference between npm run dev and npm run dev:lib?

npm run dev starts the brush-app UI development server defined in apps/brush-app/web/package.json, while npm run dev:lib launches the development environment for the brush-js JavaScript bindings library in apps/brush-js/web/package.json. Use the former when working on the user interface and the latter when modifying the core JavaScript API.

How do I build just the WebAssembly module without bundling the entire web UI?

Execute npm run build:wasm-release or npm run build:wasm-dev from within the apps/brush-app/web directory. These scripts invoke wasm-pack build directly with the appropriate --release or --dev flags, producing the ./pkg/ output without triggering the Vite bundling step that npm run build would initiate.

Can I run the benchmark reference generator without installing Python dependencies manually?

The script at crates/brush-bench-test/test_cases/generate_reference.py requires Python and dependencies compatible with the Rust benchmark crate's expectations. Ensure your Python environment matches the project specifications, then invoke the script directly to generate the .safetensors reference files used by the test suite.

Which script should I use for production deployment?

Use npm run build from the repository root, which triggers the full release pipeline defined across the workspace package.json files, including optimized WebAssembly compilation via wasm-pack and Vite bundling. Verify the output locally using npm run preview before deploying the ./dist/ contents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}