Surfaces

Express middleware v0.3.1

A zero-dependency, dev-only review-notes overlay for Node. Mount one middleware and a floating Red Pen button appears on your pages - leave typed notes, pin them to elements, and they persist to an append-only log in your repo that you are meant to commit.

User manual (PDF)

Red Pen for Express is the web sibling of the WordPress plugin. It works in any Express app, and in any Connect-style app that uses the same middleware signature. It has no database, no build step, and no runtime dependencies - it ships as plain Node and serves its overlay client as a single script. Free, MIT. Dev credit: Lincoln Tracy.

How it works

The middleware does two things. First, it watches outgoing HTML responses and injects a small overlay script tag before the closing body tag, so every page you serve gets the Red Pen button without you editing any templates. Second, it mounts a tiny notes API under a URL prefix (default /__redpen) that the overlay talks to. Notes are appended to a log in your project - .redpen/notes.jsonl, one record per line - and a derived .redpen/notes.json snapshot is written beside it for tools that read notes off disk. There is no other moving part.

Install

Red Pen for Express is not published to npm. The source lives on GitHub at github.com/LTracy86/red-pen-express - clone it somewhere near your projects, then install it into an app as a local file: dependency:

# clone once, next to your apps
git clone https://github.com/LTracy86/red-pen-express.git

# from the app you want to annotate - path is relative to the app
npm install ../red-pen-express

That writes a "red-pen-express": "file:../red-pen-express" entry into the consuming project's package.json, which resolves as a live symlink. Because it is a symlink rather than a copied package, pulling a new Red Pen version flows into every app that links it the next time that app restarts - there is no per-app reinstall step. You can also use npm link if you prefer a globally linked package.

Mount it first

Add the middleware right after you create the app, before static file serving, compression, or your routes. Mounting it early ensures the overlay is injected into responses and the notes API is reachable. Both module systems are supported.

CommonJS (require)

const express = require('express');
const redPen = require('red-pen-express');

const app = express();
app.use(redPen({ file: __dirname + '/.redpen/notes.json' }));

// ...your routes...

ES Module (import)

import redPen from 'red-pen-express';

const app = express();
app.use(redPen({ file: here + '/.redpen/notes.json' }));

In an ES Module there is no __dirname by default - derive a directory variable (for example with fileURLToPath(import.meta.url)), or omit file entirely to default to the current working directory.

Options

If you turn off auto-injection, include the overlay manually where you want it:

<script src="/__redpen/widget.js" defer></script>

Using the overlay

Start the app as usual. A red Red Pen button appears in the bottom-right corner. From there you can:

• Leave a typed note - choose a type (note, idea, problem, or question) and a priority, then write the note.
• Pin to an element - click Pin, then click any element on the page. The note is anchored to that element by a CSS selector plus a relative position. Numbered red markers render over the pinned elements and follow the page on scroll and resize.
• Locate - jump from a note back to its pinned element; the page scrolls to it and the element flashes.
• Move it through the workflow - Start and Stop move a note between Open and In progress, and Resolve closes it. Three tabs, one per state.
• Sign your notes - the name chip in the panel header sets who this browser writes as. It starts from your git identity, so a shared repo already reads correctly.
• The repository - the panel header links to "All notes" at {mount}/repo, a standalone page listing every note across every page with filters and bulk actions.
• Dark mode and a resizable panel - a moon/sun toggle in the panel header, and a drag handle on the panel's left edge. Both preferences are saved to localStorage and restored next time.

What is new in v0.3.x

v0.3.0 is the release that makes notes shareable, and v0.3.1 is the pass that made three of its headline claims actually true. The short version:

Carried over from v0.2.0

Version 0.2.0 was the "notes UX parity" milestone - it brought the overlay's day-to-day note handling in line with the WordPress plugin. Every item below is still in the current release.

Storage

All notes for an app live under .redpen/ at the project root, in two files that do different jobs:

Both are plain text you can inspect, back up, or wipe by hand. An older array-format notes.json is migrated to the log on first open, with the original kept as a .pre-jsonl-*.json backup. See Core concepts for the full note model.

The notes API

The overlay talks to a small REST API under the mount prefix. You rarely call it directly, but it is documented so you can script against it if needed.

Seeding it across many apps

Because the package installs as a live symlink, Red Pen is meant to ride along in every local app you build. The pattern is always the same three steps: install the local dependency, mount the middleware first, and make sure that app's .gitignore does not hide .redpen/ - the notes are meant to be committed. Once linked, every future Red Pen release upgrades all of those apps on their next restart, with no reinstall.

Try the demo

npm install
npm run example   # http://localhost:4000

The demo serves a small page with the overlay injected, so you can exercise the full loop - add, pin, reply, edit, start, resolve, reopen, delete - against a real .redpen/notes.jsonl.