pedronauck/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

| 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:

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

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