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

> Discover the root directory's role in Automattic/harper. It centralizes multi-language workspaces for Rust, Node.js, build commands, docs, and CI config.

- Repository: [Automattic/harper](https://github.com/Automattic/harper)
- Tags: deep-dive
- Published: 2026-07-26

---

**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`](https://github.com/Automattic/harper/blob/main/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`:

```toml
[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`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/package.json). This file defines the npm workspace configuration, aggregating packages such as [`harper.js`](https://github.com/Automattic/harper/blob/main/harper.js), the VS Code extension, and web documentation under a single monorepo structure.

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

```

Placing [`package.json`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/README.md) provides the high-level project overview, while [`ARCHITECTURE.md`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/Cargo.toml), enabling single-command builds of all Rust crates including `harper-core` and `harper-ls`.
- It coordinates JavaScript packages through [`package.json`](https://github.com/Automattic/harper/blob/main/package.json), creating a unified npm workspace for [`harper.js`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/README.md), [`ARCHITECTURE.md`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/Cargo.toml) and [`package.json`](https://github.com/Automattic/harper/blob/main/package.json) during workflow execution, enabling steps that install Rust toolchains and Node dependencies before running cross-component tests.