Dev Guide

Electron Dev Guide

Before you start developing, the Project Architecture and Electron Architecture doc should be read to know codebase design and app design.


  • Rust - to implement storage in the electron node , needs to be installed locally. If you need a rust proxy, try


Run Web Server

Read Web Dev Guide and run web server to support render process for local electron client.

Run Node Server (Optional)

If you want to debug some features with api, like cloud workspace, the node server is needed.


Build Native Package

The client depends on @affine/native, which is written by Rust, to store data into SQLite.

yarn workspace @affine/native build


Now you can start developing affine client in local.

yarn run dev:electron


Auto Attach

It is relatively easy to debug the native process by using Visual Studio Code. You can config auto attach of VSCode to always, then run dev:electron in terminal of VSCode.



You can create launch.json, and config dev:electron command, and then start it.

  "version": "0.2.0",
  "configurations": [
      "name": "Dev Electron",
      "type": "node-terminal",
      "request": "launch",
      "command": "yarn run dev:electron"

Log File

You can open the log file by invoking apis.debug.revealLogFile() in the console of local electron client.


Release Build

Electron code is built with esbuild

Electron-forge to handle package, make, signing and notarize.

In CI, the process:


We have a special workflow for signing the Windows app.

Making Local Distributions

To make local distributions (i.e., .msi, .dmg, .appimage), you may need to do a few more steps:

  1. config yarn to make packages NOT using hoist policy & NOT using hard link
  2. yarn config set nmHoistingLimits workspaces
  3. yarn config set nmMode classic
  4. clean up all node_modules
  5. on windows: dir -Path . -Filter node_modules -recurse | foreach {echo $_.fullname; rm -r -Force $_.fullname}
  6. Linux/mac: find . -name 'node_modules' -type d -prune -exec rm -rf '{}' +
  7. rerun yarn add
  8. (optional): on Mac, you may need to remove osxSign and osxNotarize fields in forge.config to by passing signing/notarize
  9. Make using DEBUG=* HOIST_NODE_MODULES=1 BUILD_TYPE=canary yarn workspace @affine/electron make


Some diagrams (maybe outdated)