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

> Learn how to build Automattic/harper with our comprehensive guide. Compile Rust, generate WebAssembly, and bundle JavaScript for seamless integration.

- Repository: [Automattic/harper](https://github.com/Automattic/harper)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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:

```bash
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:

```bash
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`](https://github.com/Automattic/harper/blob/main/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`:

```bash
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`](https://github.com/Automattic/harper/blob/main/harper.js) package. Configuration and build options are documented in [`harper-wasm/README.md`](https://github.com/Automattic/harper/blob/main/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:

```bash
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`](https://github.com/Automattic/harper/blob/main/packages/harper.js/README.md) for API usage examples.

### Building the Web Interface

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

```bash
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`](https://github.com/Automattic/harper/blob/main/harper.js) library. Build instructions are available in [`packages/web/README.md`](https://github.com/Automattic/harper/blob/main/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.

```bash
cd harper-ls
cargo build --release

```

The resulting `harper-ls` executable appears in `target/release/`. See [`harper-ls/README.md`](https://github.com/Automattic/harper/blob/main/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:

```bash
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`](https://github.com/Automattic/harper/blob/main/harper-desktop/README.md).

## Building Editor Extensions

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

### VS Code Extension

```bash
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`](https://github.com/Automattic/harper/blob/main/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:

```bash
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`](https://github.com/Automattic/harper/blob/main/harper-core/README.md), [`harper-wasm/README.md`](https://github.com/Automattic/harper/blob/main/harper-wasm/README.md), [`packages/harper.js/README.md`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/harper.js) build process copies these into the npm package distribution.