The best way to control Claude Code, Codex and more from any computer or phone
fix(desktop): skip prepared server bytecode on Linux (#28700)
Yash Singh committed
Nov 1, 2026 at 09:04 UTC
80120b1aa34a3125c05da393c8616c2076f5888d
3 files changed
+32
-6
docs/operations/development.md
+7
-6
@@ -263,18 +263,19 @@ options.
263
264
### Prepared server bytecode
265
266
-Native desktop artifact builds generate server bytecode with the packaged Electron executable,
267
-after ASAR creation and before signing. Cross-platform and cross-architecture builds skip this
268
-step explicitly. CLI, SEA and WSL runtimes keep their existing behavior; only desktop backend
269
-imports covered by generation receive prepared bytecode. Worker-only modules compile normally.
266
+Native macOS and Windows desktop artifact builds generate server bytecode with the packaged
267
+Electron executable, after ASAR creation and before signing. Linux builds skip generation until
268
+native packaging and relocated AppImage reuse have been validated. Cross-platform and
269
+cross-architecture builds also skip generation explicitly. CLI, SEA and WSL runtimes keep their
270
+existing behavior; only desktop backend imports covered by generation receive prepared bytecode.
271
+Worker-only modules compile normally.
272
273
Electron's Node 24 cache has no read-only option and includes the producer UID in its directory
274
name. The backend links individual prepared files into its writable cache with keys for the
275
installed module paths. Node replaces files atomically, so regeneration cannot write through those
276
links into signed resources. Windows uses hard links and falls back to normal caching when volumes
277
differ or resource permissions prevent linking. Protected installations therefore may not reuse
276
-prepared bytecode. No cache bytes are copied during startup. AppImage backends discard their links
277
-on normal exit because each mount changes module paths.
278
+prepared bytecode. No cache bytes are copied during startup.
279
280
The key calculation follows Node's internal portable ESM format. Generation checks that the
281
packaged engine produced the expected CLI entry and fails the build if that format changes.
scripts/lib/server-compile-cache.test.ts
+20
@@ -2,9 +2,29 @@
2
import * as NodeFS from "node:fs";
3
import * as NodeOS from "node:os";
4
import * as NodePath from "node:path";
5
+import * as NodeURL from "node:url";
6
import { expect, it } from "vite-plus/test";
7
import { cacheKey, seedPreparedCache } from "./server-compile-cache.ts";
8
9
+it.each(["x64", "arm64"])("skips prepared bytecode generation on Linux %s", async (arch) => {
10
+ const { spawnSync } = await import("node:child_process");
11
+ const hook = NodeURL.fileURLToPath(
12
+ new URL("../prepare-server-compile-cache.cjs", import.meta.url),
13
+ );
14
+ const result = spawnSync(
15
+ process.execPath,
16
+ [
17
+ "-e",
18
+ `Object.defineProperty(process, "platform", { value: "linux" });
19
+ Object.defineProperty(process, "arch", { value: ${JSON.stringify(arch)} });
20
+ require(${JSON.stringify(hook)})({ electronPlatformName: "linux", arch: ${arch === "x64" ? 1 : 3} }).catch(error => { console.error(error); process.exitCode = 1; });`,
21
+ ],
22
+ { encoding: "utf8" },
23
+ );
24
+ expect(result.status, result.stderr).toBe(0);
25
+ expect(result.stdout).toContain("Skipping unsupported target linux");
26
+});
27
+
28
it("seeds relocated cache entries without allowing writes into shipped resources", () => {
29
const root = NodeFS.realpathSync(
30
NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-prepared-test-")),
scripts/prepare-server-compile-cache.cjs
+5
@@ -6,6 +6,11 @@ const os = require("node:os");
6
7
// afterPack runs before signing and installer creation, against the final ASAR layout.
8
module.exports = async ({ appOutDir, electronPlatformName, arch, packager }) => {
9
+ // Linux packaging and relocated AppImage cache reuse still need native validation.
10
+ if (electronPlatformName !== "darwin" && electronPlatformName !== "win32") {
11
+ console.log(`[server-compile-cache] Skipping unsupported target ${electronPlatformName}`);
12
+ return;
13
+ }
14
const targetArch = ["ia32", "x64", "armv7l", "arm64", "universal"][arch];
15
if (electronPlatformName !== process.platform || targetArch !== process.arch) {
16
console.log(