How to Build Automattic/harper: Complete Guide to the Harper Monorepo

To build Automattic/harper, compile the Rust core with cargo build --workspace --release, generate the WebAssembly module using wasm-pack build --target web --release in harper-wasm/, and bundle the JavaScript packages with pnpm run build in packages/harper.js/ and packages/web/.

Harper is a multi-language monorepo maintained by Automattic that combines Rust core crates, WebAssembly bindings, Node.js packages, and a Tauri-based desktop application. Whether you are contributing to the grammar engine or packaging the VS Code extension, understanding how to build Automattic/harper from source requires navigating three distinct layers: the Rust core, the WASM/JavaScript bridge, and the desktop editor integrations.

Prerequisites for Building Harper

Before compiling any component, install the required toolchains on your system.

1. Rust toolchain – Run rustup default stable to install Cargo and the standard library.
2. Node.js (≥ 18) and pnpm – Install pnpm globally with npm i -g pnpm.
3. wasm-pack – Install via Cargo: cargo install wasm-pack.
4. just (optional) – A command runner that simplifies task execution: cargo install just.

Clone the repository and enter the workspace:

git clone https://github.com/Automattic/harper.git
cd harper

Building the Core Rust Components

The foundation of Harper resides in several Rust crates located in the repository root. These include harper-core (the grammar engine), harper-comments, harper-cli, harper-stats, and harper-dictionary-wordlist.

Compile the entire workspace:

cargo build --workspace --release

This command produces optimized binaries and libraries in target/release/. The harper-core crate contains the core linting logic used by all downstream components. For specific implementation details, see harper-core/README.md.

Compiling the WebAssembly Module

The harper-wasm crate bridges the Rust engine to JavaScript environments. Navigate to the WASM directory and build with wasm-pack:

cd harper-wasm
wasm-pack build --target web --release

This generates harper_wasm_bg.wasm and accompanying JavaScript glue code in the pkg/ directory. The output powers browser-based integrations and the harper.js package. Configuration and build options are documented in harper-wasm/README.md.

Building the JavaScript Packages

Harper provides JavaScript wrappers and a web interface that consume the WASM artifact.

Building harper.js

This package bundles the WASM binary for Node.js and browser usage:

cd packages/harper.js
pnpm i
pnpm run build

The build script automatically copies the WASM output from harper-wasm/pkg/ into the distribution. Refer to packages/harper.js/README.md for API usage examples.

Building the Web Interface

The documentation site and demo UI reside in packages/web/:

cd packages/web
pnpm i
pnpm run build

For local development with hot reload, use pnpm run dev instead. The site uses Vite for bundling and depends on the shared lint-framework package alongside the freshly built harper.js library. Build instructions are available in packages/web/README.md.

Building the Language Server

The harper-ls binary implements the Language Server Protocol (LSP) for integration with editors like Neovim, Helix, and VS Code.

cd harper-ls
cargo build --release

The resulting harper-ls executable appears in target/release/. See harper-ls/README.md for configuration and integration details.

Building the Desktop Application

Harper Desktop is a Tauri application that packages the Rust core, WASM module, and a SvelteKit frontend.

For development with live reload:

cd harper-desktop
just dev-desktop

This command automatically installs Node dependencies, compiles the Rust side, and launches the Tauri window. For production bundles, use platform-specific commands:

• Linux: just build-desktop-linux
• macOS: just build-desktop-macos

Complete Tauri configuration and packaging options are documented in harper-desktop/README.md.

Building Editor Extensions

Optional components include IDE plugins that communicate with harper-ls.

VS Code Extension

cd packages/vscode-plugin
pnpm i
pnpm run compile

This produces the extension package ready for installation or sideloading. See packages/vscode-plugin/README.md for debugging and publishing procedures.

Obsidian and Browser Extensions

The Obsidian plugin and Chrome/Firefox extensions follow the same pattern: pnpm i && pnpm run build within their respective directories. Each contains a dedicated README with plugin-specific build instructions.

Using Just for Task Automation

If you installed the just command runner, you can orchestrate common tasks without memorizing individual commands. Running just in the repository root lists available recipes:

just

Common tasks include dev-desktop, build-desktop-linux, lint, and test. The Justfile at the repository root defines these shortcuts, streamlining the development workflow across the heterogeneous codebase.

Summary

• Automattic/harper is a monorepo combining Rust, WASM, and TypeScript components.
• Build the Rust core first with cargo build --workspace --release to generate the grammar engine and CLI tools.
• Compile harper-wasm using wasm-pack build --target web --release to create the JavaScript bridge.
• Install JavaScript dependencies with pnpm i and bundle packages with pnpm run build in packages/harper.js/ and packages/web/.
• Build the language server in harper-ls/ and the desktop app in harper-desktop/ using just dev-desktop.
• Reference specific README files (harper-core/README.md, harper-wasm/README.md, packages/harper.js/README.md, etc.) for component-specific details.

Frequently Asked Questions

Do I need to build the entire monorepo to test a single component?

No. Each layer can be built independently provided its dependencies are satisfied. For example, you can build and test harper-core changes without compiling the Tauri desktop app, but modifying harper-wasm requires rebuilding the JavaScript packages that consume it.

Why does the build require both Cargo and pnpm?

Harper uses Rust for performance-critical grammar parsing and spell-checking logic, while the editor extensions and web interfaces require Node.js tooling. The WebAssembly layer (harper-wasm) connects these ecosystems, necessitating both toolchains.

What is the fastest way to start the desktop application for development?

Run just dev-desktop from the harper-desktop/ directory. This single command handles dependency installation, Rust compilation, and launches the Tauri app with hot module replacement enabled for the frontend.

Where are the compiled WASM files located after building?

After running wasm-pack build --target web --release in harper-wasm/, the generated harper_wasm_bg.wasm and JavaScript bindings appear in harper-wasm/pkg/. The harper.js build process copies these into the npm package distribution.

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