Electron Production Build & Release Guide
This skill provides enterprise-grade best practices for building, signing, releasing, and distributing Electron applications with emphasis on security, reliability, performance, and user trust.
Quick Reference
- Build Configuration: For electron-vite production config, bundle optimization, and pre-build checks.
- Code Signing: Platform-specific signing for Windows (EV certificates), macOS (Developer ID + notarization), and Linux (GPG).
- Auto-Updates: electron-updater configuration, staged rollouts, and update testing.
- Release Workflows: GitHub Actions CI/CD pipelines for multi-platform builds.
- Distribution: GitHub Releases, Cloudflare R2, or private server hosting.
Core Principles
- Security First: All production builds must be code-signed; macOS builds must be notarized.
- Pre-Build Verification: Always run
pnpm audit,pnpm run typecheck,pnpm run lint, andpnpm run testbefore builds. - Semantic Versioning: Follow SemVer strictly (MAJOR.MINOR.PATCH).
- Staged Rollouts: Release to a percentage of users first, then expand gradually.
Build Strategy
Pre-Build Checklist
Before every production build:
- Check dependencies for vulnerabilities:
pnpm audit - Verify code quality:
pnpm run typecheck && pnpm run lint - Run test suite:
pnpm run test && pnpm run test:e2e - Check bundle size:
pnpm run build:analyzer - Verify environment configuration
Production Build Optimization
- Remove all
console.loganddebuggerstatements - Tree-shake unused dependencies
- Split vendor chunks (React, UI libraries)
- Compress images and assets
- Lazy load non-critical modules
- Disable source maps for distribution (ship separately if needed)
- Use production-mode build flags
Target Bundle Sizes
| Component | Target |
|---|---|
| Main process | < 2 MB |
| Renderer | < 5 MB |
| Total package | < 150 MB |
| Install size | < 250 MB |
Code Signing
Windows (EV Certificate Required)
Microsoft requires Extended Validation (EV) certificates since June 2023.
Recommended: Use cloud-based signing (DigiCert KeyLocker or Azure Trusted Signing).
Never use self-signed certificates for distribution.
macOS (Developer ID + Notarization)
Two-step process:
- Code Signing: Uses Developer ID Certificate
- Notarization: Apple scans for malware (required for distribution)
Key requirements:
hardenedRuntime: truein electron-builder config- Valid entitlements.mac.plist
- APPLE_TEAM_ID, APPLE_ID, and APPLE_APP_SPECIFIC_PASSWORD environment variables
Linux (GPG)
Sign release artifacts with GPG:
gpg --detach-sign -u YOUR_KEY_ID dist/packages/*.AppImage
gpg --detach-sign -u YOUR_KEY_ID dist/packages/*.debAuto-Update Implementation
electron-updater Configuration
Configure publish provider in electron-builder.yml:
publish:
provider: github
owner: your-username
repo: your-repo
releaseType: releaseStaged Rollout Strategy
Reduce risk by gradually rolling out updates:
- Day 1: 10% of users
- Day 2: 25% of users
- Day 3: 50% of users
- Day 4: 100% of users
If issues detected:
- Do NOT release same version again (users will ignore update)
- Release a higher version (e.g., 1.0.1 -> 1.0.2)
- Consider reverting to previous version if critical bug
Testing Auto-Update Locally
Use dev-app-update.yml for local testing. Test the full update cycle before releasing.
Release Workflow
Manual Release Checklist
Before creating release tag:
- Merge all PRs for this version
- Bump version in
package.json - Update
CHANGELOG.md - Run full test suite
- Run bundle analysis
- Test build locally
- Verify app starts and basic features work
- Test auto-update mechanism
Creating a Release
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3GitHub Actions automatically handles:
- Building for Windows, macOS, Linux
- Code signing
- Notarization (macOS)
- Creating GitHub Release
- Publishing artifacts
Distribution Options
GitHub Releases (Recommended)
- Free and reliable
- Built-in auto-update support
- Version management
- Release notes
Cloudflare R2
S3-compatible storage with R2 endpoint. Configure environment variables:
- R2_BUCKET_NAME
- R2_ACCOUNT_ID
- R2_ACCESS_KEY_ID
- R2_SECRET_ACCESS_KEY
- UPDATE_FEED_URL
Private Server (Generic HTTP)
Requires serving latest.yml, latest-mac.yml, and all artifacts via HTTPS.
Security Checklist
Before release, verify:
- Dependencies audited (
pnpm audit) - No hardcoded secrets in code
- IPC channels validated
- CSP properly configured
- Context isolation enabled
- Node integration disabled in renderer
- Sandbox enabled for all windows
- Auto-update tested end-to-end
- Code signing certificates valid
- macOS app notarized
- All communications over HTTPS
- No sensitive data in logs or error messages
Troubleshooting
| Issue | Solution |
|---|---|
| Auto-update not triggering | Verify latest.yml exists, check GitHub releases config |
| Code signing fails | Renew certificate, verify fingerprint |
| Windows SmartScreen warning | Distribute widely, file with Microsoft for reputation |
| macOS "cannot verify developer" | Re-notarize, check team ID and certificate |
| Large app download | Analyze with ANALYZE=true pnpm run build, enable compression |
| Blank screen in production | Use relative paths (base: './'), verify build output |
Validation Checklist
Before finishing a task involving Electron releases:
- Pre-build checks pass (audit, typecheck, lint, test)
- Bundle sizes within targets
- Code signing configured for all platforms
- macOS notarization configured
- Auto-update mechanism implemented and tested
- Staged rollout strategy defined
- Security checklist completed
- Release notes prepared
For detailed configuration examples, code samples, and GitHub Actions workflows, refer to references/patterns.md.