Developer Guide

Developer guide

This page gets you from a fresh Windows PC to a running OpenNote window. It is a short version of CONTRIBUTING.md, which is the source of truth. Read that file before you open a pull request. By taking part, you agree to follow the code of conduct.

Set up on Windows

Install these tools once, in this order:

1. Microsoft C++ Build Tools, with the "Desktop development with C++" workload. Install it before Rust.
2. WebView2. It ships with Windows 10 and 11, so you usually have it.
3. Rust stable, through rustup, with the default stable-msvc toolchain.
4. Node.js 22.18 or newer, the long-term support release.
5. Git.

On macOS or Linux, install the Tauri prerequisites instead of steps 1 and 2.

Open a new terminal, then clone the repository and start the app:

git clone https://github.com/XrxcGH/OpenNote.git
cd OpenNote
npm install && npm start

The first start compiles the Rust dependencies, which takes several minutes. Later starts are much faster. Windows PowerShell 5.1 doesn't accept &&, so run npm install and npm start on separate lines there, or use PowerShell 7 or Command Prompt.

Also run this once, so CHECKS runs before each commit:

npm run setup-hooks

Everyday commands

Command	What it does
npm start	Runs the desktop app in development mode with live reload
npm test	Runs the CHECKS tests and the UI tests
npm run lint	Lints TypeScript and JavaScript
npm run typecheck	Type-checks all TypeScript
npm run format	Formats code with Prettier
npm run checks	Runs CHECKS on files changed since origin/main
npm run tokens	Regenerates the design tokens from brand/tokens.json

The full list of scripts, and the Rust commands, are in CONTRIBUTING.md. See Testing and quality for what each check covers.

Make a change

1. For a small fix, open a pull request right away. For a new feature, open an issue first, so everyone can agree that it fits the current phase.
2. Branch off the phase branch in progress, such as phase-2, and open the pull request into it. A fix outside any phase branches off main and targets main.
3. Keep the pull request small, under about 400 changed lines, and add screenshots for visual changes in both themes.
4. Write the commit subject in the imperative mood, under about 72 characters.
5. Make sure every CI check passes, and get one approving review.

Details are in Development process.

Two rules to remember

• UI code uses design tokens only. To change how OpenNote looks, edit brand/tokens.json, run npm run tokens, and commit both together. Never edit the generated files by hand.
• Anything hard to reverse needs an architecture decision record before the code. See Design decisions.

Where to go next

• Architecture overview explains how the parts fit together.
• Repository map shows where things live.
• Testing and quality covers the CHECKS gate.
• Releasing is for maintainers.
• The development plan and the brand guide describe what to build and how it should feel.
• Report security problems privately, as the security policy describes.