How to Build the Harper Project from Source: Complete Guide

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)
• Node.js – version 20 or higher
• pnpm – version 10.10.0 (pinned in 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:

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 used for deterministic CI builds. The repository structure is defined by 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.

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 wrapper.

Build the Language Server

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

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:

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:

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

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:

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:

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

Or build and run the release version:

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

Verify the Build

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

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.

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