Build from Source
Clone the repository and build Daintree from source: prerequisites, the native-module split, the script surface, output directories, and packaging.
Daintree is an Electron app: a Vite-built React renderer, an ESBuild-bundled main process, and a handful of native modules. Building it is an ordinary npm install followed by npm run dev. The parts that trip people up are the pinned Node version and the native rebuild, so both get their own sections below.
Prerequisites
- Git. Use a maintained Git installation; this checkout does not declare a Git 2.30 build-time minimum.
- Node.js 22.23.2. The version is pinned identically in
.nvmrc,.node-version, and theengines.nodefloor inpackage.json. A CI check (npm run check:node-version) fails the build if those three ever drift apart. Use nvm or fnm to match it. - npm. Ships with Node. The repo is an npm workspace, so npm is the supported package manager.
- A C/C++ toolchain and Python, to compile
node-ptyand Daintree's two small process-teardown addons against Electron's ABI. All three are built from source on every install.
Daintree runs on Electron 42 (Chromium 148). You don't install Electron yourself; it comes down as a devDependency.
Platform build tools
node-gyp/README.md for the tool versions supported by your checkout.Install the Xcode Command Line Tools:
xcode-select --installInstall the Visual Studio Build Tools with the Desktop development with C++ workload, either from the Visual Studio installer or with winget:
winget install Microsoft.VisualStudio.2022.BuildTools Install Python as well. For Windows ARM64, include the ARM64 C++ compiler and ATL components; the package manager command alone does not select every required workload.
On Debian-family systems, start with Python, make and a C/C++ toolchain:
sudo apt install build-essential python3Clone & Install
git clone https://github.com/daintreehq/daintree.git
cd daintree
nvm install
nvm use
npm install Use npm install for day-to-day development and npm ci for clean or CI builds. Either is fine; the difference is whether the lockfile is treated as authoritative.
--ignore-scripts. It skips the postinstall native rebuild, and the app crashes on startup with a module-version error that looks nothing like the cause.The repository also contains six workspace packages under packages/: the plugin author packages @daintreehq/plugin-sdk (whose ./testing entry replaces the old separate testing package), @daintreehq/plugin-vite, the daintree-plugin CLI and create-daintree-plugin, plus two internal packages the app itself uses: @daintreehq/tour (the welcome-tour engine) and the private @daintreehq/svelte-source-model (behind the Element Picker's Svelte source tracing). The root install links these workspaces; npm run packages:build is the explicit compilation step.
Native Modules
This is the one part of the build that isn't obvious, and it's the most common cause of a failed first install.
The postinstall script (also reachable as npm run rebuild) first patches node-pty's binding.gyp with one compile-time define, so a PTY exit that lands while the pty-host is shutting down can no longer abort it. It then rebuilds exactly three modules from source against the Electron runtime, never from a prebuilt binary, because the patch only exists in a source build:
node-pty: the pseudo-terminal binding every terminal panel sits on.win-job-object: Windows process-tree teardown, fromelectron/native/in the repository.posix-pty-reaper: the macOS and Linux equivalent, from the same folder.
It then runs node-pty's own post-install step, which fetches the ConPTY assets on Windows and exits cleanly everywhere else. That step always runs, even if one of the rebuilds failed, because it's idempotent and skipping it would leave Windows without a working ConPTY. Any failure (the patch, a rebuild or that step) is listed at the end and makes the install exit non-zero, so a broken native build is not silently carried forward.
better-sqlite3 is deliberately excluded. Since version 13 it is an N-API addon that loads a prebuilt binary shipped inside the package. N-API is ABI-stable, so the same prebuild works under both Node and Electron, and version 13's binding.gyp suppresses source compilation whenever a prebuild is present. Rebuilding it would emit gyp metadata and nothing else. If you're following older instructions that tell you to run an electron-rebuild step for better-sqlite3, delete that step; it no longer does anything.
Windows on arm64
Windows arm64 needs one extra pass, because the default rebuild targets the host architecture. It rebuilds win-job-object for arm64 and reruns node-pty's post-install step:
npm run rebuild:win-arm64 Development
npm run dev This starts the Vite renderer dev server and the Electron main process together. Renderer changes hot-reload; main-process changes trigger an automatic restart. If the renderer's dev-server port is busy, the script picks the next free one. A development build keeps its settings and sessions in a separate daintree-dev user-data folder, so it never shares state or the single-instance lock with an installed Daintree. Two variants are worth knowing:
npm run dev:fresh: same thing, but against a brand-new, empty user-data folder created in the system temp directory (daintree-dev-fresh-*). You get a first-run state for onboarding and setup testing, and your normaldaintree-devsettings and sessions are left untouched. Each run starts from a new empty folder.npm run dev:perf: turns on internal performance capture and writesperf-metrics.ndjson.
The Script Surface
| Script | What it does |
|---|---|
npm run check | The full gate chain: typecheck, then every codegen and drift check, then lint ratchet and format check. This is what has to be clean before you push. |
npm run fix | Runs Prettier and ESLint with autofix across the repository. Review the diff for changes outside your task. |
npm run typecheck | Typechecks the renderer, the main process, the preload, every workspace package, and the plugin, plugin-view, perf and E2E projects. Runs with an 8 GB heap because the project graph is large. |
npm run lint / lint:fix | ESLint over the repo. |
npm run format / format:check | Prettier. |
npm test / test:watch | Vitest unit tests. test:integration runs the integration config. |
npm run test:e2e | Playwright against an E2E build (npm run build:e2e). Choose the spec or project you need; this is a separate, expensive check. Project-scoped variants exist (test:e2e:core, test:e2e:full, and the per-suite full-* projects). |
npm run packages:build | Builds the six workspace packages. |
npm run perf | The performance harness. |
npm run rebuild | Re-runs the native-module rebuild described above. |
npm start, no npm run preview, no npm run serve, and no standalone npm run electron. If a guide tells you to run one of those, it isn't describing this repository.Production Build
npm run build This runs tsc, builds the renderer with Vite, and bundles the main process, with an 8 GB Node heap. The build, typecheck, and packaging commands have different outputs:
| Directory | Contents |
|---|---|
dist/ | The Vite-built renderer. |
dist-electron/ | The bundled main process and preload. |
dist-typecheck/ | Output from the main-process project-reference leg of npm run typecheck. Build artifacts only; nothing ships from here. |
release/ | electron-builder distributables, created by packaging rather than npm run build alone. Override with -c.directories.output=<path>. |
Run the Built App
npm run dev:electron That's electron . with NODE_ENV=development set. Electron reads the "main" field in package.json, which points at dist-electron/electron/bootstrap.js, so you're launching whatever npm run build last produced. It's the quickest way to check a production build without packaging it.
electron is already a devDependency, so nothing extra is downloaded. Running npx electron . directly works too; it just skips the NODE_ENV that the script sets for you.Package for Distribution
npm run package:mac Writes DMG and ZIP artifacts to release/ for three architectures: arm64, x64, and universal. It isn't one universal binary; you get all three variants, each named with its architecture.
npm run package:win Builds both Windows targets: an .appx for the Microsoft Store (x64) and an NSIS .exe installer (x64 and arm64). There is no portable-executable target. To build just one, use npm run package:win:nsis or npm run package:win:appx.
npm run package:linux Writes an AppImage and a .deb to release/.
npm run package does the same thing and lets electron-builder pick the target for your current platform. Every packaging script passes --config electron-builder.config.cjs: electron-builder does not find that file on its own, and a bare npx electron-builder falls back to its defaults (wrong targets, the default icon, output in dist/). If you call electron-builder directly, pass the same flag.
Local unsigned macOS builds
For a local macOS build with no Developer ID signing and no notarization, use the local packaging script rather than calling electron-builder yourself:
npm run package:local:dmg # a DMG
npm run package:local # an unpacked .app in release/ It runs npm run build first, so the package never carries a stale bundle. Signing follows your environment: with CSC_LINK pointing at an existing Developer ID certificate the build is signed; without it the build is unsigned. An unsigned build also skips Electron's fuse flipping, because flipping fuses patches the Electron framework binary and invalidates its signature, and with nothing to re-sign it macOS on Apple Silicon kills the app at launch. Notarization is skipped unless APPLE_API_ISSUER is set. That is why a hand-written electron-builder command with signing switched off is not a substitute: it either misses the project config or flips the fuses.
The notarization hook itself is gated separately by DAINTREE_SKIP_NOTARIZATION=true. Release builds do notarize, and the hook submits and waits as two steps: notarytool submit, then notarytool wait --timeout 1800. The wait is bounded so an Apple-side delay can't block CI indefinitely, and a resumable .notarization-state.json in the output directory lets a re-run reattach to an in-flight submission instead of resubmitting.
Fast local install loop
On macOS, if you want the built app installed rather than just packaged, there's a dedicated loop:
npm run package:local: a--dirpackage (no installer).npm run package:local:dmg: the same, as a DMG.npm run install:local: builds a--dirpackage and installs it into/Applications.npm run install:local:fast: installs the most recent build already inrelease/, without building.
The local packages are stamped with a development version one minor above package.json plus the build date (a repo at 0.43.0 produces something like 0.44.0-dev.20261013), so a local build is never confused with a release. package.json itself is not changed.
/Applications and shares its settings and sessions. A Daintree that is already running is left alone and picks up the new build when you quit and reopen it. Until then, helper processes it starts can already load code from the new bundle, so restart soon.--dir package ships without app-update.yml, so the auto-updater is deliberately inert in it. That's expected, not a bug. See When Auto-Update Is Disabled.Source reference
Check package.json and .nvmrc for the audited scripts and runtime pin, postinstall.cjs for native modules, and electron-builder.config.cjs for packaging targets, and package-local-dmg.mjs for local signed and unsigned macOS packages. The app's contributor guide covers the development workflow. Plugin authors can usually work in their own repository; start with Building & Distributing plugins.
Troubleshooting
node-pty build failures
If npm install fails during the native rebuild:
- Confirm the platform build tools are installed (see Prerequisites).
- Rebuild by hand:
npm run rebuild - On macOS, make sure the Xcode CLI tools are current:
xcode-select --install - On Windows arm64, run
npm run rebuild:win-arm64as well.
If the failure names better-sqlite3, the problem is upstream of the rebuild (the package's prebuild wasn't downloaded) because Daintree never rebuilds it.
Wrong Node.js version
Daintree pins Node 22.23.2. If you see a version error, switch to the pinned version:
nvm install # reads .nvmrc automatically
nvm use npm run check:node-version verifies that .nvmrc, .node-version, and engines.node still agree.
Stale renderer after a dependency change
Delete node_modules/.vite to clear Vite's cache, then restart the dev server.