Skip to content

Development

Setup

Terminal window
nvm use # Node 26 (.nvmrc)
npm install
npm run dev # electron-vite with HMR

Supported platforms: Linux x64 and Windows x64. mkvtoolnix is not required on your machine: install the sidecars from the app (onboarding or Settings → Video tools).

Scripts

Script Purpose
npm run dev Electron with HMR
npm test / test:watch Vitest (Main in Node, renderer in jsdom)
npm run typecheck tsc for main/preload (node) and renderer (web)
npm run lint / format ESLint / Prettier
npm run db:generate Generate a Drizzle migration from src/main/database/schema
npm run db:check Validate migration consistency
npm run build Typecheck + electron-vite build
npm run dist:linux / dist:win Package on a native runner (used by CI)
npm run build:win Build the Windows installer from Linux (wine in Docker)
npm run build:all Linux + Windows locally
npm run icons Regenerate icons from resources/icon.svg
npm run clean Remove out/, dist/ and the ESLint cache

Before opening a pull request

Terminal window
npm run lint && npm run typecheck && npm test && npm run db:check

CI (.github/workflows/release.yml) only runs on tags and manual dispatch, so run these locally.

Conventions

  • Process boundaries: the renderer never touches Node or Electron. A new capability means a channel in src/shared/ipc-contract.ts, a handler built with createHandler (Zod validation), the preload allowlist and a typed hook in src/renderer/src/data/. See ipc.md.
  • Main process: separation of concerns (repositories, services, parsers, lexers). Keep logic that does not need electron in plain modules so it is testable in Node.
  • Subtitles: only text nodes reach the LLM; the AST must reassemble the file byte for byte, preserving timestamps and tags. A parser change needs round-trip tests. See parsing.md.
  • External processes: always through ProcessRunner (timeout, SIGTERM → SIGKILL, tracked for shutdown). Never call child_process directly.
  • Database: change the schema in src/main/database/schema, run npm run db:generate and commit the migration. See database.md.
  • UI text: no user-facing text from the Main, only error codes. Strings go through i18next (English is the source language, pt-BR is complete), typed keys. See renderer.md.
  • Secrets: the OpenRouter key never leaves the Main process in clear text, and logs go through the redactor. See logging.md.
  • Docs: update the matching file in docs/ in the same change. README.md and README-pt.md are for end users; technical detail belongs here.

Tests

  • Vitest, with property tests (fast-check) in the parsers.
  • Renderer tests start with // @vitest-environment jsdom and use test/fake-api.ts, a typed window.api where every unmocked call rejects. See renderer.md.
  • Manifest changes are validated by src/main/sidecars/manifest.schema.test.ts.

Releasing

See release.md.