Electron Release

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

1. Build Configuration: For electron-vite production config, bundle optimization, and pre-build checks.
2. Code Signing: Platform-specific signing for Windows (EV certificates), macOS (Developer ID + notarization), and Linux (GPG).
3. Auto-Updates: electron-updater configuration, staged rollouts, and update testing.
4. Release Workflows: GitHub Actions CI/CD pipelines for multi-platform builds.
5. 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, and pnpm run test before 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:

1. Check dependencies for vulnerabilities: pnpm audit
2. Verify code quality: pnpm run typecheck && pnpm run lint
3. Run test suite: pnpm run test && pnpm run test:e2e
4. Check bundle size: pnpm run build:analyzer
5. Verify environment configuration

Production Build Optimization

• Remove all console.log and debugger statements
• 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

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:

1. Code Signing: Uses Developer ID Certificate
2. Notarization: Apple scans for malware (required for distribution)

Key requirements:

• hardenedRuntime: true in 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/*.deb

Auto-Update Implementation

electron-updater Configuration

Configure publish provider in electron-builder.yml:

publish:
  provider: github
  owner: your-username
  repo: your-repo
  releaseType: release

Staged 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.3

GitHub Actions automatically handles:

1. Building for Windows, macOS, Linux
2. Code signing
3. Notarization (macOS)
4. Creating GitHub Release
5. 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

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.