What Is the Role of the Root Directory in Automattic/harper? The Central Hub Explained

The root directory in Automattic/harper serves as the central orchestrator that unifies a multi-language workspace, defining the Cargo workspace for Rust crates, the Node.js workspace for JavaScript packages, and high-level build commands via the justfile, while housing global documentation and CI configuration.

The Automattic/harper repository is a polyglot project spanning Rust core libraries, TypeScript plugins, and a Tauri desktop application. Its root directory functions as the single source of truth that coordinates builds, tests, and releases across these disparate ecosystems. Understanding how this top-level folder structures the workspace is essential for contributing to or extending the Harper grammar checker and language server.

Defines the Cargo Workspace for Rust Components

The Cargo.toml file at the repository root declares a unified Cargo workspace that compiles all Rust components in a single pass. This configuration eliminates version drift by managing cross-crate dependencies centrally.

The workspace members include core crates like harper-core, harper-ls, and harper-wasm:

[workspace]
members = [
  "harper-cli",
  "harper-core",
  "harper-ls",
  "harper-comments",
  "harper-wasm",
  # ...

]

Because this file resides at the root, commands like cargo build --workspace or cargo test --workspace operate on every Rust crate simultaneously. Adding a new crate requires updating this root-level Cargo.toml, ensuring the new package immediately joins the shared compilation context.

Coordinates the Node.js Monorepo

The root directory also anchors the JavaScript ecosystem through its package.json. This file defines the npm workspace configuration, aggregating packages such as harper.js, the VS Code extension, and web documentation under a single monorepo structure.

{
  "private": true,
  "workspaces": ["packages/*"],
  "scripts": {"dev": "just dev"}
}

Placing package.json at the root enables pnpm or npm commands to resolve dependencies across all JavaScript packages consistently. This eliminates the need to run separate installs in each sub-directory and ensures shared dev tools apply repository-wide.

Orchestrates Cross-Language Builds with Just

The justfile at the root abstracts complex multi-step workflows into simple, memorable commands. It acts as the primary interface for developers moving between the Rust core and TypeScript consumers.

Common root-level commands include:

• just dev-desktop – Builds shared web packages, then launches the Tauri desktop application on port 1420 (configured in harper-desktop/vite.config.js)
• just format – Runs cargo fmt, pnpm format, and other formatters across every language in the repo
• just build-desktop-linux – Cross-compiles the desktop application for Linux targets

This centralization ensures that build logic remains version-controlled and consistent across local development and CI environments.

Houses Global Documentation and Architecture

Global documentation files reside at the root to maximize visibility on the GitHub front page. The README.md provides the high-level project overview, while ARCHITECTURE.md details system design and component interactions for new contributors.

These files are strategically placed at the top level because they describe the entire ecosystem rather than individual crates or packages. Their location ensures anyone cloning the repository immediately discovers the project's purpose and contribution guidelines.

Manages CI and DevOps Configuration

The root directory contains all continuous integration and deployment scaffolding. The .github/workflows directory hosts GitHub Actions pipelines that build, test, and release every component—from harper-core to the VS Code extension.

Additional infrastructure files include:

• docker-compose.yml and Dockerfile – Container definitions for development and CI environments
• flake.nix – Reproducible build environment for Nix users
• Fastlane configuration – Mobile and desktop app distribution pipelines

Centralizing these configurations ensures that infrastructure changes apply consistently across the multi-platform project.

Provides a Unified Entry Point for Tooling

By anchoring both Cargo and npm workspaces, the root directory establishes consistent path resolutions and environment variables for every sub-project. Linting, testing, and formatting commands executed from this level operate on the entire repository, preventing configuration drift between components.

Scripts and automation tools that need to operate globally—such as release automation or security scanning—start from the root to ensure they capture every Rust crate and JavaScript package defined in the workspace manifests.

Summary

• The root directory defines a Cargo workspace via Cargo.toml, enabling single-command builds of all Rust crates including harper-core and harper-ls.
• It coordinates JavaScript packages through package.json, creating a unified npm workspace for harper.js and editor plugins.
• The justfile provides high-level commands like just dev-desktop and just format that orchestrate cross-language builds and formatting.
• Global documentation (README.md, ARCHITECTURE.md) and CI configuration (.github/workflows) reside at the root for maximum visibility.
• All repository-wide tooling commands start from this directory to ensure consistent paths and environment variables across every component.

Frequently Asked Questions

How do I add a new Rust crate to the Harper workspace?

Create the crate with cargo new my-new-crate --lib, then add the directory name to the members array in the root Cargo.toml. Because the workspace root defines all members, the new crate instantly becomes part of the shared build context, allowing imports from other workspace crates without manual path dependencies.

What command builds the entire Harper project from the root directory?

Running cargo build --workspace --release from the root compiles every Rust crate listed in Cargo.toml simultaneously. For full-stack builds that include the desktop application, use just dev-desktop, which builds the JavaScript assets first via pnpm before invoking the Rust compiler.

Why does Harper use a justfile at the root instead of npm scripts?

The justfile serves as a polyglot task runner that can orchestrate both Cargo and npm commands in a specific sequence. While npm scripts handle JavaScript-specific tasks well, just provides the root-level coordination needed to build the Rust core, then the WebAssembly bindings, then the TypeScript wrapper—all in the correct order with a single command.

Where are the CI pipelines configured in the Harper repository?

Continuous integration workflows live in the .github/workflows directory at the root directory level. This placement allows GitHub Actions to access both Cargo.toml and package.json during workflow execution, enabling steps that install Rust toolchains and Node dependencies before running cross-component tests.

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