Build Scripts in Automattic/harper: Complete Monorepo Build Guide

Yes, Automattic/harper defines npm-based build scripts in nearly every package, using Vite for most TypeScript projects and wp-scripts for the WordPress plugin.

Harper is organized as a pnpm monorepo where each package maintains its own package.json with a build script that compiles source code into distributable assets. The build scripts in Automattic/harper are standardized across the workspace, allowing developers to run pnpm run build from any package directory to trigger compilation.

Build Script Architecture

The repository uses a decentralized build strategy with no root-level Makefile or Justfile. Instead, every package that produces a distributable asset defines its own build logic in package.json. This aligns with modern JavaScript monorepo patterns, ensuring each component—from browser extensions to the desktop application—controls its own compilation pipeline.

Web Packages and Browser Extensions

These packages rely exclusively on Vite for bundling and minification:

• In packages/web/package.json: "build": "vite build -l warn" compiles the web UI.
• In packages/chrome-plugin/package.json: "build": "vite build -l warn" produces the browser extension bundle.
• In packages/vscode-plugin/package.json: "build": "vite build -l warn" builds the Visual Studio Code extension assets.

Editor Plugins

Editor-specific packages use Vite or custom pre-pack steps:

• In packages/obsidian-plugin/package.json: "build": "vite build -l warn" creates the Obsidian plugin distribution.
• In packages/harper-editor/package.json: "build": "pnpm run prepack" executes a custom pre-packaging routine that internally uses Vite.

Core Libraries and SDK

Packages exporting JavaScript libraries combine TypeScript compilation with Vite bundling:

• In packages/harper.js/package.json: "build": "tsc && vite build -l warn" first type-checks with the TypeScript compiler, then bundles with Vite.
• In packages/lint-framework/package.json: "build": "tsc && vite build -l warn" follows the same two-stage process.
• In packages/components/package.json: "build": "vite build -l warn && npm run prepack" builds the component library and prepares it for packaging.

WordPress Plugin

The WordPress integration uses the official WordPress toolchain rather than Vite:

• In packages/wordpress-plugin/package.json: "build": "wp-scripts build --webpack-copy-php" invokes wp-scripts (webpack-based) to bundle JavaScript while copying PHP files to the output directory.

Desktop Application

The desktop application compiles its frontend assets via Vite before the Rust backend compilation:

• In harper-desktop/package.json: "build": "vite build -l warn" prepares the UI assets.

How to Execute the Build Scripts

To build the core web interface using Vite:

cd packages/web
pnpm install
pnpm run build

To build the WordPress plugin using wp-scripts:

cd packages/wordpress-plugin
pnpm install
pnpm run build

To build the JavaScript SDK with type checking:

cd packages/harper.js
pnpm install
pnpm run build

Root Workspace Configuration

The root package.json defines the workspace structure but does not expose a top-level build script. According to the source code, the workspace relies on individual packages to define their own compilation steps. Developers must trigger builds from within specific package directories rather than from the repository root.

Summary

• Build scripts in Automattic/harper are defined in individual package.json files across the monorepo, with no centralized Makefile.
• Vite is the primary build tool for 8 out of 10 packages, consistently using the command vite build -l warn.
• wp-scripts handles the WordPress plugin build via webpack with the --webpack-copy-php flag.
• TypeScript compilation (tsc) precedes Vite bundling in core library packages like packages/harper.js.
• Execute builds with pnpm run build after installing dependencies in the target package directory.

Frequently Asked Questions

Does Automattic/harper use a Makefile or Justfile for builds?

No. The repository contains no Makefile, Justfile, or other non-npm build orchestration files. All build logic is encapsulated within npm scripts in each package's package.json, consistent with standard JavaScript monorepo practices.

What build tool does the Harper WordPress plugin use?

The WordPress plugin uses wp-scripts, the official WordPress build toolchain built on webpack. The build script wp-scripts build --webpack-copy-php compiles JavaScript assets while copying PHP files to the output directory, as defined in packages/wordpress-plugin/package.json.

How do I build the Harper Obsidian plugin?

Navigate to packages/obsidian-plugin and run pnpm run build. This executes vite build -l warn, which bundles the TypeScript source into the distribution format required by Obsidian. The same pattern applies to the Chrome and VS Code extensions located in packages/chrome-plugin and packages/vscode-plugin.

Is there a single command to build all Harper packages at once?

No. The root package.json does not define a workspace-wide build script. You must build packages individually by running pnpm run build in each directory (e.g., packages/web, packages/harper.js, etc.). However, you can use pnpm workspace filtering commands like pnpm --filter "./packages/**" build if supported by your pnpm version.

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