# How to Build the Harper Project from Source: Complete Guide

> Learn to build the Harper project from source with our comprehensive guide. Compile the Rust core, WASM, language server, and front-ends using Rust Nodejs and pnpm.

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

---

**Building Harper from source requires Rust 1.78+, Node.js v20+, pnpm, and the `just` task runner to compile the Rust core engine, WebAssembly module, language server, and TypeScript front-ends including the Tauri desktop app and browser extensions.**

Harper is a multi-runtime grammar engine developed by Automattic that combines a Rust-based core with JavaScript/TypeScript front-ends. When you build the Harper project from source, you compile the `harper-core` engine into both native binaries and WebAssembly, then package the language server, web interface, and editor extensions using the repository's centralized `justfile` tasks.

## Prerequisites

Before building, install the required toolchains:

- **Git** – to clone the `Automattic/harper` repository
- **Rust** – version 1.78 or higher with `cargo` (install via [rustup.rs](https://rustup.rs))
- **Node.js** – version 20 or higher
- **pnpm** – version 10.10.0 (pinned in [`harper-desktop/package.json`](https://github.com/Automattic/harper/blob/main/harper-desktop/package.json))
- **cargo-hack** and **wasm-pack** – install via `cargo install`
- **just** – the repository's task runner (install via `cargo install just` or package manager)
- **OpenSSL** – system library for TLS compilation in some Rust crates

On macOS or Linux, most dependencies can be installed via Homebrew, apt, or Chocolatey.

## Clone the Repository and Install Dependencies

Start by cloning the repository and installing JavaScript dependencies:

```bash
git clone https://github.com/Automattic/harper.git
cd harper
pnpm install

```

The `pnpm install` command installs all packages under the `packages/*` directory and generates a [`pnpm-lock.yaml`](https://github.com/Automattic/harper/blob/main/pnpm-lock.yaml) used for deterministic CI builds. The repository structure is defined by [`pnpm-workspace.yaml`](https://github.com/Automattic/harper/blob/main/pnpm-workspace.yaml) at the root.

## Build the Rust Core and WebAssembly

The core grammar engine lives in `harper-core/` and compiles into both a native library and a WebAssembly artifact (`harper-wasm`) consumed by JavaScript packages.

```bash
just build-core          # Debug build of harper-core

just build-core --release   # Optimized release build

just build-wasm          # Compile WASM target using wasm-pack

```

The resulting WebAssembly binary is placed at `packages/harper.js/dist/harper_wasm_bg.wasm` and is required by the [`harper.js`](https://github.com/Automattic/harper/blob/main/harper.js) wrapper.

## Build the Language Server

The `harper-ls` binary provides LSP support for VS Code, Neovim, Helix, and Zed:

```bash
just build-ls          # Debug build

just build-ls --release   # Release build

```

The compiled binary appears in `target/release/harper-ls` (or `target/debug/`).

## Build the Web UI

Harper's documentation site resides in `packages/web/` and uses Vite with SvelteKit:

```bash
just dev-web      # Start hot-reloading dev server on http://localhost:1420

just build-web    # Production build output to packages/web/dist

```

Port 1420 is required for the desktop app integration.

## Build the Desktop Application

The Tauri v2 desktop application embeds the web UI and runs the highlighter service:

```bash
just dev-desktop            # Build shared packages and launch Tauri dev mode

just build-desktop-linux    # Create Linux bundle (.deb/.rpm/AppImage)

just build-desktop-macos    # Create macOS bundle (.app/.dmg)

```

These commands automatically handle `pnpm install` for the front-end before invoking `cargo tauri build`.

## Build Browser Extensions

Both Chrome and Firefox extensions share code under `packages/chrome-plugin/`:

```bash
just build-chrome-extension
just build-firefox-extension

```

Load the resulting `dist/` directories as unpacked extensions in your browser.

## Build the VS Code Extension

Package the VS Code extension with:

```bash
just build-vscode-extension
code --install-extension packages/vscode-plugin/harper-vscode-*.vsix

```

## Run the CLI Tool

For debugging or direct usage, compile the `harper-cli` binary:

```bash
cargo run --bin harper-cli -- lint "Your text to check."

```

Or build and run the release version:

```bash
just build-cli
./target/release/harper-cli lint "Sample text"

```

## Verify the Build

Run the comprehensive test suite covering Rust crates, WebAssembly, and JavaScript:

```bash
just check-all

```

This executes `cargo fmt`, `cargo test`, `pnpm test`, and linting across the workspace.

## Summary

- **Install prerequisites**: Rust 1.78+, Node v20+, pnpm, cargo-hack, wasm-pack, and `just`
- **Clone and setup**: `git clone` the repository and run `pnpm install`
- **Build core components**: Use `just build-core`, `just build-wasm`, and `just build-ls` for the engine and language server
- **Compile applications**: Run `just build-web`, `just build-desktop-linux/macos`, and extension build commands for front-ends
- **Verify**: Execute `just check-all` to ensure all components pass tests

## Frequently Asked Questions

### What version of Rust is required to build Harper?

Harper requires **Rust 1.78 or higher** as specified in the root workspace configuration. The `harper-core` crate and its dependencies use language features stabilized in recent versions, so older Rust compilers will fail during compilation.

### How do I build only the Harper language server?

Run `just build-ls --release` from the repository root. This compiles only the `harper-ls` crate located in `harper-ls/` without building the desktop application or browser extensions. The binary outputs to `target/release/harper-ls`.

### Can I build the desktop app without building the web UI first?

No, the desktop application in `harper-desktop/` depends on the web UI built from `packages/web/`. The `just dev-desktop` and `just build-desktop-*` commands automatically build the web assets first, but you can manually prepare the UI by running `just build-web` before invoking Tauri commands.

### How do I verify my build is working correctly?

Execute `just check-all` to run the full verification pipeline. This command formats Rust code, runs the test suite for all crates, validates the WebAssembly build, and executes JavaScript tests via `pnpm`. If all checks pass, your local build of Harper is fully functional.