From e7f41b560942305d8c83cffa43afd075ae8f8678 Mon Sep 17 00:00:00 2001
From: Jannis Braun <151788261+TheZwiss@users.noreply.github.com>
Date: Mon, 6 Jul 2026 01:52:06 +0200
Subject: [PATCH] fix(desktop): don't let uiohook-napi rebuild abort the whole
 workspace install
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The @backspace/desktop postinstall runs `electron-rebuild -f -w uiohook-napi`,
which compiles a native module from source and needs a C++ toolchain
(make/g++/python3). On a bare host without those — a typical VPS a self-hoster
clones onto — that failure took the ENTIRE `pnpm install` down (exit 255), so the
server never installed either, even though uiohook-napi is desktop-only and
irrelevant to hosting.

Make the rebuild non-fatal: on failure it now prints a clear one-line warning and
continues. Machines with build tools (CI, desktop devs) are byte-identical — the
fallback never fires; only toolless boxes (which aren't building the desktop app
anyway) skip it. Verified on a bare x86 box: full `pnpm install` now exits 0 and
the server builds and boots from source. Docs note the build-tool requirement for
desktop work and point self-hosters at the Docker installer.
---
 CONTRIBUTING.md               | 5 +++++
 README.md                     | 8 ++++++++
 packages/desktop/package.json | 2 +-
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f6e69dd6..f2f196db 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -52,6 +52,11 @@ pnpm dev              # API server on :3005, Vite dev server on :5173
 
 You can run the two halves separately with `pnpm dev:server` and `pnpm dev:web`.
 
+Working on the **desktop** app additionally needs a C++ toolchain (`make`, `g++`,
+`python3`) to build the native `uiohook-napi` module — on Debian/Ubuntu:
+`sudo apt install build-essential python3`. Without it `pnpm install` just warns
+and skips that one rebuild; the server and web client are unaffected.
+
 Voice and video are optional and require a LiveKit server; see the README for
 configuration. Text, federation, uploads, and everything else run fully without
 it.
diff --git a/README.md b/README.md
index 2a9630f5..79b9754b 100644
--- a/README.md
+++ b/README.md
@@ -268,6 +268,14 @@ cp .env.example .env          # set JWT_SECRET (openssl rand -hex 32)
 pnpm dev                       # API server on :3005, Vite dev server on :5173
 ```
 
+> **Server/web only?** `pnpm install` also builds the desktop app's native
+> keyboard-hook module (`uiohook-napi`), which needs a C++ toolchain
+> (`make`, `g++`, `python3`). If those are missing it now **warns and continues** —
+> the server and web client don't need it. Install a build toolchain
+> (Debian/Ubuntu: `sudo apt install build-essential python3`) only if you're
+> building the **desktop** app. And to *self-host*, use the Docker installer
+> above — it never touches the desktop package.
+
 Run the halves separately if you prefer:
 
 ```bash
diff --git a/packages/desktop/package.json b/packages/desktop/package.json
index 106e859f..70c152fa 100644
--- a/packages/desktop/package.json
+++ b/packages/desktop/package.json
@@ -18,7 +18,7 @@
     "clean": "rm -rf dist dist-electron",
     "test": "vitest run",
     "test:watch": "vitest",
-    "postinstall": "electron-rebuild -f -w uiohook-napi"
+    "postinstall": "electron-rebuild -f -w uiohook-napi || node -e \"console.warn('[desktop] uiohook-napi native rebuild skipped - needs build tools (make, g++, python3). Only required to RUN the desktop app; the server, web client, and Docker image are unaffected.')\""
   },
   "dependencies": {
     "electron-updater": "^6.3.0",