How We Upgraded Our Desktop App’s Electron Framework from 15 to 29

Background

Zhiyinlou is an enterprise chat desktop client that must deliver fast response, stable network transmission, support for both macOS and Windows, rapid platform integration, and third‑party plugin integration. Electron, a popular open‑source framework that enables cross‑platform desktop apps using web technologies, was originally at version 15, which lagged behind in performance and features. Upgrading to the latest stable version (29, released in 2024) resolves issues such as PDF download failures, H.265 video preview failures, and reduces memory and CPU consumption.

Process

The upgrade was organized into four stages: research, development, testing, and gray‑release rollout. After breaking the project into sub‑tasks and estimating difficulty, each stage was scheduled and executed accordingly.

Research

Key research areas included operating‑system compatibility, API changes, and Node‑plugin adaptation.

Operating‑system compatibility : Windows 10 and later, macOS 10.15 and later are the minimum supported versions. Electron 23+ supports Windows 10, and Electron 27+ supports macOS 10.15. Since less than 5% of users were on older OS versions, version 29 was selected.

Third‑party plugin compatibility : Plugins such as Tencent Meeting, Agora voice, Baidu screen‑cast, etc., were recompiled for Electron 29 and verified using the official Electron‑quick‑start demo.

Self‑built plugin compatibility : Custom C++ plugins (network monitor, clipboard, video info, etc.) were re‑adapted to Electron 29.

Electron API changes : Deprecated APIs (e.g.,

ipcRenderer.sendTo

removed after version 27) were identified and replaced with the new recommended approaches.

Development

4.1 Adapt third‑party plugins

Third‑party plugins were recompiled for Electron 29. Some Windows plugins required upgrading C++11 code to C++17. The process was smoother than the previous upgrade from Electron 11 to 15.

4.2 Adapt self‑built plugins

Node‑gyp and NAN usage were replaced with the native N‑API as documented at nodejs.org/docs/latest/api/n-api.html . The C++ toolchain was upgraded to C++17 on Windows and the corresponding Xcode version on macOS.

4.3 Self‑maintained Electron compilation and packaging

The workflow includes source acquisition, environment setup, code modification, compilation, and artifact publishing. Jenkins automates builds on both Windows and macOS agents, uploads packages to a private NPM registry and cloud storage, and publishes symbol maps to Sentry.

4.4 Custom Electron migration

Customizations include merging multiple small windows to reduce process overhead, updating macOS notification handling to the official API, and customizing the silent‑install progress UI by modifying the ShipIt module.

4.5 Front‑end code adaptation

Upgrading Chromium from 94 to 122, Node from 16.5 to 20.9, V8 from 9.4 to 12.2, and Electron API changes required code adjustments such as replacing

ipcRenderer.sendTo

with

window.postMessage

and tightening webPreferences for security:

webPreferences: {
  webSecurity: false,
  nodeIntegration: true,
  contextIsolation: false,
  nodeIntegrationInWorker: true,
  webviewTag: true,
  affinity: 'processReuse',
  preload: path.resolve(__dirname, '../../../preload/renderer-preload.js')
}

4.6 Bug fixes

Key bugs addressed include font activation dialogs on macOS (fixed by using

CTFontCreateWithNameAndOptions

with

kCTFontOptionsPreventAutoActivation

) and Windows NSIS upgrade failures caused by a lingering C++ service, which was stopped programmatically before upgrade.

Testing and Release

After extensive testing, a two‑week gray‑release collected feedback from hundreds of active users. Following issue resolution, a second gray‑release of over two weeks was performed. The final rollout was completed in version 1.9.9, delivering improved performance and stability to all users.

Conclusion

The Electron framework upgrade for Zhiyinlou’s desktop client successfully eliminated technical bottlenecks of the old version, delivering a smoother, more stable, and more secure user experience, and exemplifying a user‑centric development philosophy.