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

> Discover Automattic/harper examples in the official repository. Run browser and Node.js demos to explore the grammar-checking engine easily.

- Repository: [Automattic/harper](https://github.com/Automattic/harper)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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`](https://github.com/Automattic/harper/blob/main/index.html) file demonstrates the essential integration pattern:

```html
<!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`](https://github.com/Automattic/harper/blob/main/README.md) in [`packages/harper.js/examples/raw-web/README.md`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/index.js) file implements a minimal script:

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

```bash
npm install @harper/dev
node index.js

```

The [`README.md`](https://github.com/Automattic/harper/blob/main/README.md) at [`packages/harper.js/examples/commonjs-simple/README.md`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/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:

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

```

Each subdirectory contains:
- A runnable implementation ([`index.html`](https://github.com/Automattic/harper/blob/main/index.html) or [`index.js`](https://github.com/Automattic/harper/blob/main/index.js))
- A [`README.md`](https://github.com/Automattic/harper/blob/main/README.md) with step-by-step instructions
- Dependencies declared via [`package.json`](https://github.com/Automattic/harper/blob/main/package.json) where applicable

The examples are kept intentionally small — the [`index.html`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/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.