Building from Source

Building from Source

Setup

You need Node 22 or newer — the main process uses node:sqlite, which is not available without a flag before that. Node 24 is what the release workflow uses.

git clone https://github.com/Lucki74/draggy.git
cd draggy
npm install

Ollama has to be installed and running, same as for a normal install.

Running it

npm run electron:dev

Vite and Electron start together with hot reload on the renderer. Changes to anything under electron/ need a restart.

npm run dev starts only Vite, which is useful for renderer work but note that window.electronAPI will be undefined — every call site guards for that, so the app loads, but anything touching the filesystem, the database or search does nothing.

Checks

npm run check

Typecheck, lint and the test suite. Around 680 tests in under two seconds; run it before every commit.

Individually: npm run typecheck, npm run lint, npm run test. npm run test:watch while working on something, npm run test:coverage for the report.

Building an installer

npm run electron:build

Windows installer into dist-electron. There is electron:build:mac, electron:build:linux and electron:build:all as well. All of them pass --publish never, so a local build cannot upload anything by accident.

The icons are generated from source art with npm run icons if you change them.

Releasing

From a clean main:

npm run check
npm version patch
git push --follow-tags

npm version writes the version into package.json, commits it and tags it. Pushing the tag starts the release workflow, which builds on Windows and Linux and publishes the installers plus the latest.yml files the in-app updater reads. It authenticates with the automatic GITHUB_TOKEN, so there is no secret to configure.

RELEASING.md in the repository has the detail, including how to publish from your own machine instead.

The version in package.json is the single source of truth. A release whose tag and package.json disagree will never be offered as an update.

macOS

macOS is not in the release workflow on purpose. Squirrel.Mac refuses to update an app that is not signed and notarised, so an unsigned build would install and then never update itself again. npm run electron:build:mac still produces a .dmg for manual distribution.

Adding it properly needs an Apple Developer certificate, CSC_LINK and CSC_KEY_PASSWORD as repository secrets, notarisation credentials, and a macos-latest entry in the workflow matrix.

Conventions

Comments explain why, not what. The codebase leans on this heavily — most of the non-obvious numbers in src/voice/constants.ts have a paragraph next to them saying where they came from, and that is the house style rather than an exception.

New behaviour that encodes a decision should be a pure function with a test. Anything needing a GPU, a network or Electron belongs at the edges where it can be stubbed.

The interface holds no English: every user-visible string goes through src/translations.ts in all twelve languages. The tests enforce this in both directions — one fails if a t() call has no matching key, another fails if a key is defined that nothing reads, so a string cannot be left behind by a feature that was removed.

Contributing

Draggy is under the GNU GPL v3.0 or later. If you are sending a patch, read CONTRIBUTING.md first — it covers the workflow above plus what opening a pull request means for copyright.

Nothing runs npm run check for you: the only GitHub workflow fires on a release tag, not on pull requests. Running it yourself is the only check there is.