# How to Set Up a Development Environment for Automattic/harper

> Quickly set up your development environment for Automattic/harper. Run `just setup` and `just dev-component` to start coding efficiently. Get started now!

- Repository: [Automattic/harper](https://github.com/Automattic/harper)
- Tags: getting-started
- Published: 2026-08-01

---

**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`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/pnpm-workspace.yaml)** – Declares JavaScript workspaces and their interdependencies
- **[`Cargo.toml`](https://github.com/Automattic/harper/blob/main/Cargo.toml)** – Top-level Cargo workspace including all Rust crates

## Step-by-Step Harper Development Environment Setup

### 1. Clone the Repository

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

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

```bash
just test-rust          # full Rust test suite

cargo build --workspace # build all Rust crates

```

**Language Server:**

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

```

**Desktop application:**

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

```

**JavaScript/Wasm library:**

```bash
cd packages/harper.js
pnpm build

```

**Editor plugins (example: VS Code):**

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

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

```bash
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`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/Cargo.toml) workspace, and [`pnpm-workspace.yaml`](https://github.com/Automattic/harper/blob/main/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.