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

> Explore Automattic/harper usage examples for browser and Node.js grammar demos. Learn to implement real-time grammar checking with the harper.lint method efficiently.

- Repository: [Automattic/harper](https://github.com/Automattic/harper)
- Tags: getting-started
- Published: 2026-07-27

---

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

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

```bash
npm install @harper/dev

```

### Linting a Static String Programmatically

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

```javascript
// 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:

```bash
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.