How to Set Up a Development Environment for Automattic/harper

Run just setup after cloning the repository to install all Rust and JavaScript dependencies, then use component-specific just commands like just dev-desktop or just dev-ls to start developing.

The Harper repository is a Rust-and-JavaScript monorepo that powers grammar-checking across editors, desktop apps, and the web. Whether you want to hack on the core engine, extend the Language Server Protocol (LSP) implementation, or build editor plugins, you'll need the right toolchains and workspace configuration. This guide walks through the complete setup process based on the official packages/web/src/routes/docs/contributors/environment/+page.md and verified against the repository's source code.

Prerequisites for Harper Development Environment Setup

You'll need four core tools installed before running the setup commands.

Tool	Purpose	Installation
Rust (stable)	Builds harper-core, harper-ls, harper-desktop	curl https://sh.rustup.rs -sSf | sh
Node ≥ 18	JavaScript packages (harper.js, editor plugins)	Use NodeSource or your package manager
pnpm v10	Workspace package manager	npm i -g pnpm@10
Just	Task runner for just setup, just dev-desktop, etc.	cargo install just

Optional: Install Nix for a one-command dev shell with all tools pre-configured.

You'll also need Git and a C compiler (for native Rust crate compilation).

Repository Structure Overview

Understanding the layout helps you navigate when setting up your Harper development environment:

/                      ← repository root
├─ Cargo.toml          ← Rust workspace definition
├─ pnpm-workspace.yaml ← JavaScript monorepo configuration
├─ justfile            ← task definitions
├─ harper-core/        ← grammar engine (Rust)
├─ harper-ls/          ← LSP implementation
├─ harper-desktop/     ← Tauri desktop application
├─ harper-js/          ← WebAssembly wrapper (npm package)
├─ packages/           ← editor plugins (VS Code, Obsidian, Chrome)
└─ docs/               ← SvelteKit documentation site

Key files that drive the setup process:

• justfile – Defines just setup, just dev-desktop, just test-rust, and other common tasks
• pnpm-workspace.yaml – Declares JavaScript workspaces and their interdependencies
• Cargo.toml – Top-level Cargo workspace including all Rust crates

Step-by-Step Harper Development Environment Setup

1. Clone the Repository

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

2. Run the Universal Setup Script

The just setup command in the repository root populates Cargo caches, installs Rust toolchains, and runs pnpm install across all JavaScript workspaces.

just setup

This internally executes cargo fetch, pnpm install, and helper scripts that download pre-built WebAssembly artifacts.

3. Verify and Select Your Development Target

Choose which component to work on and start its development server:

Core grammar engine:

just test-rust          # full Rust test suite

cargo build --workspace # build all Rust crates

Language Server:

just dev-ls             # launches harper-ls in watch mode

Desktop application:

just dev-desktop        # builds web assets, launches Tauri app

JavaScript/Wasm library:

cd packages/harper.js
pnpm build

Editor plugins (example: VS Code):

cd packages/vscode-plugin
pnpm dev                # watches TypeScript and reloads extension

4. Optional: Use Nix for Reproducible Setup

If you have Nix installed, enter a fully-prepared environment:

nix develop

This provides the correct Rust toolchain, Node, pnpm, and just binary automatically.

5. Verify Your Installation

Test the CLI against a sample sentence:

cargo run --bin harper-cli -- lint "Their is a problem with the grammar."

You should see a suggestion to replace "Their" with "There".

Essential Development Commands for Harper

Task	Command	Description
Run all tests	just test-all	Rust, JavaScript, and integration tests
Watch single crate	cargo watch -x "test -p harper-core"	Auto-rerun tests on changes
Format code	just format	cargo fmt + pnpm format
Lint JavaScript	pnpm lint	ESLint/Prettier across JS packages
Build production bundle	just build-desktop-linux	Tauri distributable (platform-specific)

Troubleshooting Common Setup Issues

Symptom	Cause	Solution
just: command not found	just not in $PATH	cargo install just; restart shell
Build fails with missing harper-core crate	Stale workspace caches	Run just setup or cargo clean
Desktop app crashes on launch	Missing system libraries	Install Tauri platform deps (e.g., libgtk-3-dev on Linux)
LSP doesn't restart after plugin edits	Out-of-sync pnpm lockfile	Delete pnpm-lock.yaml; re-run pnpm install

Summary

Setting up a Harper development environment follows this workflow:

• Install Rust, Node ≥ 18, pnpm v10, and Just
• Run just setup to bootstrap the monorepo
• Use component-specific just commands (dev-ls, dev-desktop, test-rust) for targeted development
• Consider Nix for a reproducible, one-command environment

The justfile, Cargo.toml workspace, and pnpm-workspace.yaml keep Rust and JavaScript layers synchronized for rapid iteration across the full stack.

Frequently Asked Questions

What is the fastest way to set up a Harper development environment on a new machine?

Run just setup after installing the four prerequisites (Rust, Node, pnpm, Just). This single command fetches dependencies for both the Rust workspace and JavaScript packages. If you use Nix, nix develop achieves the same result without manual tool installation.

Can I develop Harper components without installing all prerequisites?

Partially. You can work on pure Rust components with only Rust installed, or pure JavaScript plugins with only Node and pnpm. However, full integration testing and the just task runner require all tools. The desktop app additionally needs platform-specific system libraries for Tauri.

How do I run tests for a specific Harper crate during development?

Use cargo watch -x "test -p harper-core" (substituting any crate name) for automatic test re-execution. Alternatively, run just test-rust for the full suite or cargo test -p <crate-name> for one-time execution.

Where is the authoritative source for Harper environment setup documentation?

The source of truth is packages/web/src/routes/docs/contributors/environment/+page.md in the repository. This file renders the official documentation site and is maintained alongside code changes.

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