Electron App Packaging
Relevant source files
The following files were used as context for generating this wiki page:
The Electron App Packaging system for Nudge (OpenLive) is designed to bundle a low-latency native application for macOS and Windows. It integrates a Next.js web UI and an agent service into a single distributable package, ensuring local execution of servers to eliminate cold starts and network hops.
The packaging process utilizes electron-builder to manage cross-platform builds, code signing, and notarization. The architecture is characterized by "clean packaging" where application data like settings and keys are stored as small JSON files in the user-data directory rather than requiring native modules.
Sources: apps/desktop/README.md:3-10, apps/desktop/package.json:17-21
Build Pipeline and Scripting
The build process is orchestrated through a series of scripts defined in the desktop package and the workspace root. Before the final Electron build, the system performs "packing" of the web and agent services.
Build Lifecycle
The build sequence follows a specific order to ensure all resources are available for the Electron shell:
- Prebuild: Execution of
pack-web.cjsandpack-agent.cjsto bundle the Next.js app and the agent (using esbuild). - Resource Integration: Bundled services are moved to
dist/webanddist/agentto be included asextraResources. - Shell Assembly: The Electron main process (
main.cjs) and preload scripts are packaged into an ASAR archive. - Platform-Specific Distribution:
electron-buildergenerates the final.dmgfor macOS or NSIS installer for Windows.
Sources: apps/desktop/package.json:11-14, apps/desktop/README.md:14-18, apps/desktop/electron-builder.yml:15-18
The diagram above illustrates the multi-stage build pipeline from service packing to final platform distribution.
Sources: apps/desktop/package.json:11-14, apps/desktop/README.md:14-18, apps/desktop/electron-builder.yml:15-18
Configuration Management
The electron-builder.yml file defines the identity and packaging behavior of the application. Key configurations include application metadata, directory structures, and platform-specific settings.
Package Metadata and Directories
| Property | Value | Description |
|---|---|---|
appId | com.openlive.desktop | Unique application identifier |
productName | Nudge | Display name of the application |
directories.output | release | Target directory for build artifacts |
directories.buildResources | build | Directory containing icons and entitlements |
Sources: apps/desktop/electron-builder.yml:1-7
Resource Handling
The packaging strategy differentiates between shell code and background services. While the Electron shell resides in the ASAR, the servers are treated as unpacked resources spawned as child Node processes.
files:
- main.cjs
- preload.cjs
- splash.html
extraResources:
- from: dist/web
to: web
- from: dist/agent
to: agent
Sources: apps/desktop/electron-builder.yml:15-26
Platform Specifics
macOS Packaging
For macOS, the system produces a Universal DMG supporting both Apple Silicon and Intel architectures.
- Hardened Runtime: Enabled for security and notarization.
- Entitlements: Uses
build/entitlements.mac.plistfor microphone and camera permissions. - Descriptions: Explicit usage descriptions for
NSMicrophoneUsageDescriptionandNSCameraUsageDescriptionare provided to the OS.
Sources: apps/desktop/electron-builder.yml:29-45
Windows Packaging
Windows builds target the NSIS installer for x64 architecture.
- NSIS Options: Configured to allow changing installation directories and creating desktop shortcuts.
- Artifact Name: Follows the pattern
${productName}-${version}-windows.${ext}.
Sources: apps/desktop/electron-builder.yml:62-76
Code Signing and Distribution
The distribution workflow is primarily environment-driven, particularly for macOS notarization and signing.
macOS Notarization Requirements
Distribution-ready builds require three key environment variables:
APPLE_ID: The developer's Apple ID email.APPLE_APP_SPECIFIC_PASSWORD: Generated at appleid.apple.com for notarization.APPLE_TEAM_ID: Located in the Apple Developer account membership.
Sources: apps/desktop/README.md:31-45, RELEASING.md:11-13
CI/CD Integration
In the CI environment (GitHub Actions), secrets are used to provide the CSC_LINK (base64 encoded .p12 certificate) and CSC_KEY_PASSWORD.
| CI Secret | Mapping |
|---|---|
MAC_CSC_LINK | CSC_LINK |
MAC_CSC_KEY_PASSWORD | CSC_KEY_PASSWORD |
Sources: apps/desktop/electron-builder.yml:47-52, RELEASING.md:11-13
This sequence shows the interaction between the CI environment and Apple's services during the packaging process.
Sources: apps/desktop/README.md:31-50, apps/desktop/electron-builder.yml:47-52
Summary
The Electron App Packaging system provides a robust framework for delivering Nudge as a native application. By leveraging electron-builder and a structured prebuild process, it effectively bundles standalone Next.js and agent services while managing complex cross-platform requirements like universal macOS binaries and automated notarization.
Sources: apps/desktop/README.md:3-10, apps/desktop/electron-builder.yml:1-10