Automattic/harper Usage Examples: How to Run the Browser and Node.js Grammar Demos

Harper provides ready-to-run browser and Node.js demos in packages/harper.js/examples/ that demonstrate real-time grammar checking with the harper.lint method.

The Automattic/harper repository ships with minimal, runnable examples that integrate the core grammar-checking engine into web pages and server-side scripts. These demos live under packages/harper.js/examples/ and need no complex build step beyond loading a Wasm module from a CDN or installing the @harper/dev NPM package. Whether you are prototyping a web integration or automating text validation, these Harper usage examples provide the fastest path to working code.

Harper Browser Demo (raw-web)

The browser demo in packages/harper.js/examples/raw-web/ provides a complete HTML page that loads the Harper Wasm bundle via CDN and lints text from a <textarea> in real time. Its accompanying README.md walks through the required script tags, making this the quickest way to see the grammar engine running without bundlers or build tools.

Loading the Harper Wasm Module

The index.html file imports the Harper class directly from unpkg.com using an ES module <script> tag. This pulls down the compiled Wasm artifact automatically, so you do not need to manage the binary yourself.

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Harper Demo</title>
    <!-- Load the Harp‑Wasm bundle from the CDN -->
    <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>

Calling the Lint API

Inside the event listener, the code instantiates new Harper() and awaits harper.lint(text), which returns an array of diagnostic objects. The results are serialized to JSON and injected into the <pre id="output"> element for immediate inspection.

Harper Node.js Demo (commonjs-simple)

The server-side demo in packages/harper.js/examples/commonjs-simple/ demonstrates programmatic grammar checking in a Node.js environment using CommonJS require syntax. Its README.md covers the install command and API calls, so you can integrate this pattern into scripts, CI pipelines, or backend services.

Installing the Harper Package

The demo requires the @harper/dev package, which bundles the grammar engine and its Wasm backend for the Node.js runtime. Install it locally before running the script.

npm install @harper/dev

Linting a Static String Programmatically

The index.js file creates a Harper instance and passes a hard-coded string to the async lint method. It then logs the structured grammar results to the console as formatted JSON.

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

// Create a Harper instance (defaults use the curated dictionary)
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);

Run the demo with the following command:

node index.js

Summary

• The Automattic/harper repository maintains ready-to-run demos under packages/harper.js/examples/ for both browser and Node.js environments.
• The raw-web demo loads Harper from a CDN via an ES module <script> tag and calls harper.lint() in response to user input.
• The commonjs-simple demo installs @harper/dev via NPM and uses require("@harper/dev") to lint strings in a Node.js process.
• Both examples rely on the same core async lint instance method and require no additional toolchain beyond a modern browser or Node.js runtime.

Frequently Asked Questions

Where are the official Harper usage examples located?

According to the Automattic/harper source code, all official demos live in the packages/harper.js/examples/ directory. The two primary subdirectories are raw-web/ for browser integrations and commonjs-simple/ for server-side JavaScript.

Do I need to build Harper from source to run the examples?

No. The browser demo loads the pre-built Wasm module directly from the unpkg.com CDN, and the Node.js demo only requires running npm install @harper/dev. Neither example requires compiling the Rust codebase or building the desktop extension.

What API method does Harper expose for grammar checking?

Both demos call the async lint method on a Harper instance. After instantiating with new Harper(), you pass a string to await harper.lint(text) and receive a JSON-serializable array of grammar and spelling diagnostics.

Can I use Harper in a CommonJS project?

Yes. The commonjs-simple example explicitly uses const { Harper } = require("@harper/dev"), demonstrating that Harper supports CommonJS require syntax out of the box for server-side JavaScript projects.

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