Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge/desktop): externalize node-pty in the electron-vite main build (#2472)

Nick Gomezd8e12c6e3b89
diff --git a/.changeset/fix-terminal-node-pty-externalization.md b/.changeset/fix-terminal-node-pty-externalization.md
new file mode 100644
index 000000000..a47bbb638
--- /dev/null
+++ b/.changeset/fix-terminal-node-pty-externalization.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fixed the desktop in-app terminal failing on every open with "The terminal stopped unexpectedly." in v0.25.0 (Restart Terminal included). Moving node-pty to optionalDependencies had stopped electron-vite from externalizing it, so the packaged pty host bundled node-pty's loader and could no longer reach the native binding. node-pty is now explicitly externalized in the main-process build, and a packaging guard test pins the seam.
diff --git a/packages/desktop/electron.vite.config.ts b/packages/desktop/electron.vite.config.ts
index 232efc248..2614cf745 100644
--- a/packages/desktop/electron.vite.config.ts
+++ b/packages/desktop/electron.vite.config.ts
@@ -47,6 +47,15 @@ export default defineConfig({
externalizeDeps: true,
sourcemap: 'hidden',
rollupOptions: {
+ // node-pty lives in optionalDependencies (a failed native build must
+ // not fail `bun install` on toolchain-less machines), but electron-vite's
+ // `externalizeDeps: true` externalizes `dependencies` ONLY. Without this
+ // explicit external, rolldown bundles node-pty's JS into out/main/chunks/
+ // and its __dirname-relative native loader can no longer reach
+ // app.asar.unpacked/node_modules/node-pty/ — every packaged terminal
+ // spawn then fails ("The terminal stopped unexpectedly.", the v0.25.0
+ // stable regression). Pinned by electron-builder-node-pty-deps.test.ts.
+ external: ['node-pty'],
// Two entries in the main bundle: the main-process entry itself AND
// the utility-process entry that main.forks. electron-vite's config
// only has `main`/`preload`/`renderer` sections — there is no native
diff --git a/packages/desktop/tests/unit/electron-builder-node-pty-deps.test.ts b/packages/desktop/tests/unit/electron-builder-node-pty-deps.test.ts
index 30989674f..a8af770ea 100644
--- a/packages/desktop/tests/unit/electron-builder-node-pty-deps.test.ts
+++ b/packages/desktop/tests/unit/electron-builder-node-pty-deps.test.ts
@@ -118,3 +118,32 @@ describe('node-pty desktop packaging config', () => {
}
});
});
+
+describe('node-pty electron-vite externalization', () => {
+ /**
+ * electron-vite's `externalizeDeps: true` externalizes ONLY `dependencies` —
+ * optionalDependencies are never consulted. With node-pty pinned in
+ * optionalDependencies (load-bearing, see above), it MUST be named as an
+ * explicit rollup external in the main build, or rolldown bundles node-pty's
+ * JS into out/main/chunks/ and its __dirname-relative native loader can no
+ * longer reach app.asar.unpacked/node_modules/node-pty/ — every terminal
+ * create then fails with spawn-error ("The terminal stopped unexpectedly.",
+ * v0.25.0 stable regression).
+ */
+ test('node-pty is externalized in the main build despite optionalDependencies placement', async () => {
+ const config = (await import('../../electron.vite.config.ts')).default as {
+ main?: { build?: { rollupOptions?: { external?: unknown } } };
+ };
+ const external = config.main?.build?.rollupOptions?.external;
+ const externals = Array.isArray(external) ? external : [external];
+ const pkg = readPkg();
+ const autoExternalized = 'node-pty' in (pkg.dependencies ?? {});
+ expect(
+ autoExternalized || externals.includes('node-pty'),
+ 'node-pty must be externalized in the electron-vite main build. It lives in optionalDependencies, ' +
+ "which externalizeDeps: true does NOT cover (it reads pkg.dependencies only) — add 'node-pty' to " +
+ 'main.build.rollupOptions.external in electron.vite.config.ts, or the bundled loader breaks every ' +
+ 'packaged terminal spawn.',
+ ).toBe(true);
+ });
+});