How to Set Up Automattic/harper Locally: A Complete Development Guide

To set up Automattic/harper locally, install Rust (1.78+), Node.js (18+), pnpm (10.10.0), and wasm-pack, clone the repository, and run just setup to bootstrap the workspace with all Rust crates and JavaScript packages.

Harper is a multi-language grammar-checking platform built around a Rust core (harper-core) that compiles to native binaries, a WebAssembly module (harper-wasm), a JavaScript wrapper (harper.js), a language-server implementation (harper-ls), and a desktop Tauri app (harper-desktop). When you set up Automattic/harper locally, you gain the ability to modify the core engine, WebAssembly bindings, JavaScript API, editor extensions, and the desktop overlay.

Prerequisites

Before cloning the repository, ensure your system has the following tools installed. These versions are enforced by configuration files in the repository root.

• Rust (stable 1.78+): Compiles the core engine and desktop native code. The exact version is pinned in rust-toolchain.toml in the repository root.
• Node.js (18+): Required for JavaScript and TypeScript packages. The repository includes an .nvmrc file for version management.
• pnpm (10.10.0): The monorepo uses pnpm workspaces to resolve inter-package links. This version is pinned in harper-desktop/package.json.
• wasm-pack: Builds the WebAssembly binary that harper.js loads in the browser.
• Tauri CLI (2.x): Needed to run the desktop application during development. Install via cargo install tauri-cli.

On macOS, you may need Xcode command-line tools. On Linux, install build-essential, libssl-dev, and pkg-config alongside wasm-pack.

Clone the Repository

Start by cloning the source code and changing into the directory:

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

The root README.md contains the official clone instructions and links to further documentation.

Install Toolchains

Rust

Install and activate the stable Rust toolchain specified in the repository:

rustup toolchain install stable
rustup default stable

The rust-toolchain.toml file at the repository root defines the required version, ensuring consistency across development environments.

Node.js and pnpm

If you use nvm, install the correct Node.js version from the .nvmrc file:

nvm install
nvm use

Then install the exact version of pnpm required by the workspace:

npm install -g pnpm@10.10.0

This version is enforced because pnpm-workspace.yaml relies on specific workspace protocol features to link harper.js and the web UI packages.

Bootstrap the Workspace

The project uses the just task runner to orchestrate complex build steps. The justfile in the repository root defines the setup task, which installs all workspace dependencies and compiles the Rust crates.

Run the bootstrap command:

just setup

This executes pnpm install, cargo fetch, and wasm-pack build in sequence, ensuring the harper-wasm package is available for the JavaScript applications.

Build Core Components

Compile the Rust Core

Build the core library and command-line interface:

just build-core

This command compiles harper-core and related crates as defined in the root Cargo.toml workspace manifest.

Build WebAssembly

Generate the WebAssembly module for browser and Node.js usage:

just build-wasm

This runs wasm-pack and outputs the compiled .wasm bundle to harper-wasm/pkg, which harper.js imports. The pnpm-workspace.yaml file includes this path to make the package available to dependents.

Run Development Servers

Web UI

Start the Vite development server for the web interface:

just dev-web

The server launches on http://localhost:1420 as configured in packages/web/vite.config.ts. This port is also proxied by the Tauri development server when running the desktop app.

Desktop Application

Launch the Tauri desktop application with live reloading:

just dev-desktop

This builds the shared packages, compiles the Rust backend in harper-desktop/src-tauri/, and opens the overlay application. See harper-desktop/README.md for architecture details regarding the highlighter service.

Language Server

Start the language server for editor integration:

just dev-ls

This runs the binary defined in harper-ls/Cargo.toml, enabling grammar checking in VS Code, Neovim, and other LSP-compatible editors.

Verify Your Setup

Run the complete test suite to ensure all components function correctly:

just test-all

This executes Rust unit tests for harper-core, WASM binding tests, JavaScript/TypeScript tests for harper.js, and integration tests across the workspace. The testing strategy is outlined in ARCHITECTURE.md.

Summary

• Install Rust 1.78+, Node.js 18+, pnpm 10.10.0, and wasm-pack before cloning the repository.
• Run just setup from the repository root to install dependencies and build Rust crates according to the justfile definitions.
• Use just dev-web to start the web UI development server at http://localhost:1420 (configured in packages/web/vite.config.ts).
• Use just dev-desktop to launch the Tauri application with the highlighter service.
• Execute just test-all to validate the entire workspace against the test suite defined in ARCHITECTURE.md.

Frequently Asked Questions

What version of Rust do I need to build Harper?

You need Rust 1.78 or later. The repository pins the exact version in rust-toolchain.toml at the root. Running rustup default stable ensures your toolchain meets this requirement before compiling harper-core or harper-ls.

Why does the setup require pnpm instead of npm?

The monorepo uses pnpm workspaces to manage inter-package links between harper.js, the web UI, and the VS Code extension. The exact version (10.10.0) is pinned in harper-desktop/package.json to ensure consistent dependency resolution hoisting across the JavaScript packages.

How do I lint text using the local command-line interface?

After building the core, run cargo run --bin harper-cli -- lint "Your text" from the repository root. This executes the binary defined in harper-core/Cargo.toml without installing Harper system-wide, allowing you to test core grammar rules directly.

Can I develop the language server without running the desktop app?

Yes. Run just dev-ls to start the language server independently. This connects to supported editors like VS Code or Neovim via LSP, and the implementation is defined in harper-ls/Cargo.toml without requiring the Tauri runtime.

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