Where to Find and Run Automattic/Harper Examples: A Complete Guide

You can find official Harper examples in packages/harper.js/examples/, which includes ready-to-run browser and Node.js demos that demonstrate the core grammar-checking engine without building the full desktop or VS Code extensions.

The Harper repository ships with minimal, self-contained example projects that show how to integrate its spell-checking and grammar engine into web pages and server-side scripts. These examples are maintained alongside the source code and serve as the authoritative reference for developers exploring the library.

Browser Demo: Real-Time Linting in HTML

The raw-web demo (packages/harper.js/examples/raw-web/) provides a complete browser implementation. It loads the Harper Wasm module from a CDN and lints user input in real time.

The index.html file demonstrates the essential integration pattern:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Harper Demo</title>
    <script type="module">
      import { Harper } from "https://unpkg.com/@harper/dev@latest/dist/harper.js";

      const harper = new Harper();

      document.getElementById("run").addEventListener("click", async () => {
        const text = document.getElementById("input").value;
        const result = await harper.lint(text);
        document.getElementById("output").textContent = JSON.stringify(result, null, 2);
      });
    </script>
  </head>
  <body>
    <textarea id="input" rows="6" cols="60">Your text here…</textarea>
    <button id="run">Run Harper</button>
    <pre id="output"></pre>
  </body>
</html>

The accompanying README.md in packages/harper.js/examples/raw-web/README.md explains the required script tags and how to call Harper.lint from JavaScript.

Key Implementation Details

• The Wasm bundle loads from unpkg.com — no build step required
• Harper.lint() returns a promise that resolves to lint results
• Results are serialized as JSON for display or further processing

Node.js Demo: Server-Side Grammar Checking

The commonjs-simple demo (packages/harper.js/examples/commonjs-simple/) shows how to use Harper in a Node.js environment with CommonJS modules.

The index.js file implements a minimal script:

// index.js
const { Harper } = require("@harper/dev");

const harper = new Harper();

async function run() {
  const text = "Harper is a great tool for grammar checking.";
  const result = await harper.lint(text);
  console.log(JSON.stringify(result, null, 2));
}

run().catch(console.error);

To run this Harper example:

npm install @harper/dev
node index.js

The README.md at packages/harper.js/examples/commonjs-simple/README.md covers the install command and API calls needed for programmatic linting.

Where Each Example Fits Your Project

Example	Best For	Key File Path
raw-web	Static sites, CDN-based deployments, quick prototyping	packages/harper.js/examples/raw-web/index.html
commonjs-simple	Node.js backends, CLI tools, server-side processing	packages/harper.js/examples/commonjs-simple/index.js

Both examples use the curated dictionary by default — no additional configuration required to start detecting spelling and grammar issues.

How to Navigate the Examples in the Repository

Clone the Harper repository and locate the examples:

git clone https://github.com/Automattic/harper.git
cd harper/packages/harper.js/examples/

Each subdirectory contains:

• A runnable implementation (index.html or index.js)
• A README.md with step-by-step instructions
• Dependencies declared via package.json where applicable

The examples are kept intentionally small — the index.html in raw-web is under 30 lines, and the Node.js demo is under 15 lines — making them easy to adapt to your own codebase.

Summary

• Primary location: All Harper examples live in packages/harper.js/examples/
• Browser integration: Use raw-web for CDN-based Wasm loading with Harper.lint()
• Node.js integration: Use commonjs-simple for server-side grammar checking via require("@harper/dev")
• No build required: The browser demo runs directly from unpkg; the Node demo needs only npm install @harper/dev
• Reference documentation: Each example directory includes a README.md with complete setup instructions

Frequently Asked Questions

Where is the official Harper browser example located?

The official browser example is at packages/harper.js/examples/raw-web/index.html in the Automattic/harper repository. It demonstrates loading the Harper Wasm module from unpkg and calling Harper.lint() on textarea content.

Does Harper require a build step to run the examples?

No. The browser example loads @harper/dev directly from a CDN via <script type="module">. The Node.js example requires only npm install @harper/dev before running with node index.js.

What Harper API method do the examples demonstrate?

Both examples use harper.lint(text), which returns a promise resolving to an array of lint results. This is the core API for spell-checking and grammar analysis in Harper.

Can I use these examples in production applications?

The examples are designed for learning and prototyping. They use sensible defaults (curated dictionary, latest unpkg version) but lack production considerations like error boundaries, version pinning, and result caching that production deployments should implement.

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