Finishing flash.comma.ai #59

[noahspahn]

Summary

This PR adds Electron support to flash.comma.ai, enabling the web application to run as a native desktop application across Windows, macOS, and Linux platforms. The implementation maintains full compatibility with the existing web version while adding enhanced USB device access and native desktop features.

Motivation

• Cross-Platform Support: Enable users on all major desktop platforms to access the flashing tool
• Enhanced USB Access: Provide more reliable USB device detection and permissions handling
• Native Experience: Offer a native desktop app experience with proper window management
• Offline Capability: Allow the app to run without browser dependencies
• Enterprise Deployment: Enable easier distribution and deployment in enterprise environments

Changes Made

Core Electron Implementation

• Main Process (electron/main.js): Application lifecycle, window management, USB permissions
• Preload Script (electron/preload.js): Secure IPC bridge with context isolation
• Build Configuration: Cross-platform build setup for Windows, macOS, and Linux
• Auto-updater: Built-in update mechanism using electron-updater

Enhanced USB Device Handling

• Automatic QDL device detection (VID: 0x05C6, PID: 0x9008)
• Platform-specific USB permission handling
• Device connection/disconnection event handling
• Improved error messaging for USB issues

Development & Build Tools

• Development scripts with hot reload
• Platform-specific build commands
• Comprehensive build configuration for distribution
• Updated dependencies and tooling

Testing Instructions

Prerequisites

bun install

Development Testing

1. Start Development Mode:

   bun run electron-dev

   • Verify the app launches successfully
   • Confirm hot reload works when editing React components
   • Check that USB device detection works

2. Test USB Functionality:

   • Connect a comma device in QDL mode
   • Verify device appears in the interface
   • Test the flashing process end-to-end
   • Confirm device disconnection is handled gracefully

3. Platform-Specific Testing:

   • Test window management (minimize, maximize, close)
   • Verify native menus and shortcuts work
   • Check that external links open in system browser

Production Build Testing

1. Build for Current Platform:

   bun run electron-build

2. Install and Test:

   • Install the generated package
   • Test app launch from desktop/start menu
   • Verify USB permissions work without browser
   • Test auto-updater functionality (if configured)

Cross-Platform Testing

Build for all platforms:

bun run electron-build-all

Test on available platforms:

• Windows: NSIS installer, USB driver requirements
• macOS: DMG package, code signing verification
• Linux: AppImage and .deb packages, udev rules

Screenshots/Media

Development Environment

Desktop Application

Windows	macOS	Linux

| |

USB Device Detection

Build Outputs

Demo Video

https://github.com/user-attachments/assets/c03e181b-a06e-43e6-a211-5ab552e34701
4x Speed

Checklist

Development

• Electron app launches successfully in development mode
• Hot reload works for React components
• DevTools are accessible in development
• USB device detection works correctly
• All existing web functionality is preserved

Security

• Context isolation is enabled
• USB device filtering works correctly

Cross-Platform Builds

• Windows build completes successfully
• macOS build completes successfully
• Linux build completes successfully
• All platforms can install and run the app
• USB permissions work on all platforms

Documentation

• README updated with Electron instructions
• Platform-specific setup documented
• Build instructions are clear

Backward Compatibility

• Web Version: All existing web functionality remains unchanged
• API Compatibility: No breaking changes to existing APIs
• Configuration: Existing config files work without modification
• Dependencies: Core dependencies remain compatible

Deployment Notes

New Dependencies

{
  "electron": "^28.1.0",
  "electron-builder": "^24.9.1",
  "electron-updater": "^6.1.7",
  "concurrently": "^8.2.2",
  "wait-on": "^7.2.0",
  "cross-env": "^7.0.3"
}

Build Artifacts

• Windows: .exe installer (NSIS)
• macOS: .dmg package
• Linux: .AppImage and .deb packages

---

Related Issues: #[59]
Breaking Changes: None
Documentation: Updated in this PR

[adeebshihadeh]

Trying to run this on my macbook and getting:

[0] $ vite
[0]
[0]   VITE v6.2.6  ready in 387 ms
[0]
[0]   ➜  Local:   http://localhost:5173/
[1] $ cross-env NODE_ENV=development electron .
[1] /Users/adeebshihadeh/src/flash/node_modules/electron/index.js:17
[1]     throw new Error('Electron failed to install correctly, please delete node_modules/electron and try installing again');
[1]     ^
[1]
[1] Error: Electron failed to install correctly, please delete node_modules/electron and try installing again
[1]     at getElectronPath (/Users/adeebshihadeh/src/flash/node_modules/electron/index.js:17:11)
[1]     at Object.<anonymous> (/Users/adeebshihadeh/src/flash/node_modules/electron/index.js:21:18)
[1]     at Module._compile (node:internal/modules/cjs/loader:1692:14)
[1]     at Object..js (node:internal/modules/cjs/loader:1824:10)
[1]     at Module.load (node:internal/modules/cjs/loader:1427:32)
[1]     at Module._load (node:internal/modules/cjs/loader:1250:12)
[1]     at TracingChannel.traceSync (node:diagnostics_channel:322:14)
[1]     at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
[1]     at Module.require (node:internal/modules/cjs/loader:1449:12)
[1]     at require (node:internal/modules/helpers:135:16)
[1]
[1] Node.js v24.4.1
[1] error: script "electron" exited with code 1
[1] wait-on http://localhost:5173 && bun run electron exited with code 1

Already tried wiping everything with git clean -xdff.

[noahspahn]

Trying to run this on my macbook and getting:

[0] $ vite
[0]
[0]   VITE v6.2.6  ready in 387 ms
[0]
[0]   ➜  Local:   http://localhost:5173/
[1] $ cross-env NODE_ENV=development electron .
[1] /Users/adeebshihadeh/src/flash/node_modules/electron/index.js:17
[1]     throw new Error('Electron failed to install correctly, please delete node_modules/electron and try installing again');
[1]     ^
[1]
[1] Error: Electron failed to install correctly, please delete node_modules/electron and try installing again
[1]     at getElectronPath (/Users/adeebshihadeh/src/flash/node_modules/electron/index.js:17:11)
[1]     at Object.<anonymous> (/Users/adeebshihadeh/src/flash/node_modules/electron/index.js:21:18)
[1]     at Module._compile (node:internal/modules/cjs/loader:1692:14)
[1]     at Object..js (node:internal/modules/cjs/loader:1824:10)
[1]     at Module.load (node:internal/modules/cjs/loader:1427:32)
[1]     at Module._load (node:internal/modules/cjs/loader:1250:12)
[1]     at TracingChannel.traceSync (node:diagnostics_channel:322:14)
[1]     at wrapModuleLoad (node:internal/modules/cjs/loader:235:24)
[1]     at Module.require (node:internal/modules/cjs/loader:1449:12)
[1]     at require (node:internal/modules/helpers:135:16)
[1]
[1] Node.js v24.4.1
[1] error: script "electron" exited with code 1
[1] wait-on http://localhost:5173 && bun run electron exited with code 1

Already tried wiping everything with git clean -xdff.

@adeebshihadeh

Fix Electron build issues on Apple Silicon Macs
Issue:
Electron builds were failing on some Macs due to native dependency compilation errors
Root Cause:
The build process was attempting to compile native dependencies using Bun's package manager, which doesn't handle native module compilation as reliably as npm.
Solution:
Modified package.json to use npm for Electron-specific commands while keeping Bun for other operations:

Changed: "electron" script to use npm instead of direct electron execution
Added: "electron-npm" script that properly sets NODE_ENV and runs electron via npm
Updated: "electron-dev" script to use the new npm-based electron command

Key Changes:
json{
"scripts": {
"electron": "npm run electron-npm",
"electron-npm": "cross-env NODE_ENV=development electron .",
"electron-dev": "concurrently "bun run dev" "wait-on http://localhost:5173 && npm run electron-npm""
}
}
Testing:

M4 Mac mini: No issues (original development environment)
M1 MacBook Air: Now builds successfully (was previously failing)

Please test and confirm:
Could you verify that this resolves the build issues on your system? Specifically:

bun run electron-dev now works without errors
bun run electron-build completes successfully
The built application runs properly

Screen.Recording.2025-07-28.at.10.05.45.PM.mov

Note I did not have my device connected for the demo video so the usb error message is not representative of an unexpected error.