How Yuque Built a Secure, High‑Performance Desktop App with Electron

Yuque's desktop client, a productivity tool, has been iterating rapidly for over two years while maintaining healthy business growth.

This article shares the technical architecture considerations and practices behind the desktop client, as well as general solutions and experiences for desktop applications.

Desktop Client Overview

Yuque, incubated from Ant Group's experience technology team, is a note and document knowledge base. Two years ago, to provide creators with a better experience, the team launched a desktop client.

The desktop client focuses on four key aspects:

Non‑intrusive, immersive creation experience.

System‑level resident for faster launch and one‑click startup.

Integration of OS capabilities such as multi‑window, system menus, shortcuts, file I/O, and software integration.

Offline support for weak network conditions.

Architecture Overview

The architecture is divided into three left layers and supporting services on the right.

The bottom layer consists of Yuque's infrastructure and cloud services, along with security and storage modules.

The middle layer provides application‑level capabilities, including helper utilities, main‑process modules, management functions, and UI‑related modules.

The top layer hosts business applications, including core desktop modules and sub‑applications.

Key Architectural Points

Compared with ordinary web apps, the desktop client emphasizes security, software upgrades, and common desktop capabilities.

Security

Basic Security

Secure download mechanisms to prevent malicious replacement of installation packages.

Upgrade to the latest Electron version, following major releases and referencing leading apps like VSCode.

Encrypt locally downloaded files such as images and attachments.

Startup Security

Antivirus software: Sign binaries to avoid being blocked and improve startup speed.

Debugging prohibition: Prevent client-side debugging of downloaded code.

Database key management: Encrypt local database files to make them unreadable if stolen.

Application Security

Whitelist rendering containers to block malicious pages.

Disable Node APIs and enable isolation in the renderer process.

Apply web security mitigations within Electron.

Software Upgrade

The client consists of Electron/Node base packages plus business code.

Mac OS: Use hdiutil to simulate manual installation; restart completes the upgrade.

Windows: After downloading the installer, the main process launches the installer UI for manual step‑by‑step installation.

Initial full‑package upgrades caused high bandwidth consumption and poor user experience, leading to an incremental update solution where only business code is updated.

Mac implements incremental updates by replacing downloaded code; Windows requires a helper .exe to close the app, replace files, and relaunch, handling file locks and UAC permissions via PowerShell.

Reusable Core Capabilities

Multi‑window management: Open, close, and monitor performance of multiple editor windows.

Webview lifecycle: Unified module to manage webview instances used by editors and sub‑apps.

Offline/online detection: Accurate status detection on Windows, encapsulated in a common module.

Architectural Focus

Delivery Efficiency

Over 60% of desktop features mirror the web version, initially using a monorepo with shared code in a Common directory.

Key practices:

Move generic code to Common to avoid cross‑platform incompatibilities.

Use webpack alias to map platform‑specific implementations.

Define multi‑platform development standards to prevent pitfalls.

Challenges of the monorepo approach include dependency issues, lagging feature parity, compatibility problems, and lack of sandbox isolation.

To address these, the team adopted a sub‑application model, embedding independent HTML pages (online or offline) within the desktop container, similar to mini‑programs.

Benefits of sub‑apps:

Independent release cycles improve iteration speed.

Automatic access to desktop‑provided JSBridge capabilities.

Process‑level isolation ensures stability.

Webview pre‑warming and caching mitigate loading delays.

Performance

Performance optimization is ongoing and covers several areas:

Startup speed: Cache main‑process code, show loading early, and run tasks concurrently.

Main‑process load: Minimize work in the main process to avoid UI jank and crashes.

Web optimizations: Apply lazy loading, module bundling, and other web techniques.

Webview optimizations: Pre‑heat webviews and enforce performance controls.

Continuous monitoring includes daily performance metrics, automated long‑run usage simulations to catch memory leaks, and a performance dashboard for online health.

Stability

Higher stability requirements than web demand rigorous testing.

Practices include:

Unit and integration tests to catch regressions.

UI Automation (UIA) using the self‑developed Macaca‑MacOS framework for end‑to‑end testing.

Stability dashboards and real‑time alerts.

Weekly preview releases to reduce integration risk.

Conclusion

Select an architecture that matches current business scale and team expertise; consider alternatives like Flutter or Tauri based on maturity and stability.

Performance and stability improvements are continuous; establish metrics and monitoring.

Delivery efficiency and quality are critical evaluation criteria, directly influencing business outcomes.