Prerequisites

• Node.js 20+
• pnpm (run corepack enable, which picks up the version pinned in package.json's packageManager field)

Install

pnpm install

No browser install step is needed: the scraper only attaches to an already-running browser over CDP (see Use a Windows Chrome from WSL via CDP); it never launches a Playwright-managed browser.

Run the editor in development

pnpm dev

This starts:

• the Rust API on http://127.0.0.1:3002, or on an ephemeral port when 3002 is already taken (the bound port is printed)
• the Vite app on http://localhost:5173 (or the next free port), proxying /api to the port the API actually bound

scripts/dev.mjs reads the bound port from the server output and passes it to Vite, so parallel worktrees don't fight over ports. A mutating request that loses the cross-process write gate answers 409 until the other instance's write finishes.

Use a Windows Chrome from WSL via CDP

The packaged desktop app (Windows and macOS) launches its own CDP-enabled Chrome automatically when you use Auto Populate, so no manual setup is needed there — see Build the Tauri editor. The steps below are for running the editor server directly (e.g. pnpm dev in WSL), where nothing launches Chrome automatically.

If you run the editor server in WSL but want to see and interact with a Windows Chrome window for bot checks, launch Chrome on Windows with remote debugging enabled and point the server at it. The scraper reads the current HTML from the already open tab whose URL matches the requested note URL.

1. Start Chrome on Windows with a dedicated profile:

chrome.exe --remote-debugging-port=9222 --remote-debugging-address=0.0.0.0 --user-data-dir="C:\temp\noteharbor-cdp"

2. Verify the CDP endpoint is up:

http://localhost:9222/json/version

3. Start the editor server in WSL. By default it uses http://localhost:9222:

pnpm dev

To override the CDP URL:

NOTE_HARBOR_BROWSER_CDP_URL=http://localhost:9222 pnpm dev

If localhost:9222 is not reachable from WSL, use the Windows host IP instead. In many WSL setups this is the nameserver value from /etc/resolv.conf.

Workflow:

1. Open the target note page manually in the CDP browser.
2. Solve any challenge manually.
3. Trigger scrape or preview in Note Harbor.
4. The server reads the current DOM from the matching open tab.

Build the web editor and run the server

pnpm --filter editor_ui_react build
NOTE_HARBOR_SERVE_WEB_DIST=true cargo run -p editor_server_rust

This serves apps/editor/ui-react/dist from the Rust server.

Build the Tauri editor

pnpm --filter editor_desktop_tauri build

The Tauri package:

• builds the React UI
• embeds the Rust server and built web app
• bundles the current data/ directory
• copies bundled data into the user-data folder when the packaged app is newer

On Windows and macOS, the packaged app launches its own CDP-enabled Chrome automatically when you use Auto Populate, so no manual CDP setup is needed for scraping there. See NOTE_HARBOR_CHROME_PATH in Environment variables if Chrome isn't found at its standard install location.

For Windows artifacts, build on Windows:

pnpm build:editor:tauri:windows

For Linux artifacts:

pnpm build:editor:tauri:linux

For macOS artifacts (.app and .dmg), build on macOS:

pnpm build:editor:tauri:macos

For macOS artifacts (.app and .dmg), build on macOS:

pnpm build:editor:tauri:macos

Run the Flutter viewer locally

pnpm dev:viewer:flutter

This runs the native Flutter viewer on the default connected device/emulator.

Build the Flutter viewer app

Build the native viewer app, then import a .zip archive exported from the editor on first launch:

pnpm build:viewer:flutter:windows

For iOS builds:

pnpm build:viewer:flutter:ios

Environment variables

Set these environment variables to override defaults.

| Variable | Default | Description | |---|---|---| | HOST | 127.0.0.1 | API bind host | | PORT | 3002 | API bind port; an explicitly set value fails instead of falling back when taken | | NOTE_HARBOR_API_PORT | PORT or 3002 | Vite dev /api proxy target port | | NOTE_HARBOR_WRITE_GATE_TIMEOUT_MS | 5000 | How long a mutating request waits for another Editor instance before answering 409 | | NOTE_HARBOR_BROWSER_CDP_URL | http://localhost:9222 | CDP endpoint for the browser that already has the target page open | | NOTE_HARBOR_DATA_DIR | data | Root data directory containing banknotes.db and images/ | | NOTE_HARBOR_WEB_DIST_DIR | apps/editor/ui-react/dist | Static web build served by the Rust server | | NOTE_HARBOR_SERVE_WEB_DIST | false | Enables serving the built web app from the Rust server |

The

…