EPIC — Packaging & Distribution Reference

EPIC — Packaging & Distribution Reference

Installer Targets

NSIS (Windows)

  • What: Traditional Windows installer wizard (.exe)
  • Pros: Start Menu shortcut, Add/Remove Programs entry, uninstaller, user can choose install location
  • Cons: Can silently fail with very large apps (7+ GB), requires WiX-like toolchain
  • Config: target: nsis in electron-builder.yml
  • Output: release/EPIC Setup X.X.X.exe
  • Best for: Small-to-medium sized apps (<2 GB)

MSI (Windows)

  • What: Windows Installer package (.msi)
  • Pros: Built into Windows, proper install/uninstall, enterprise-friendly, Group Policy support
  • Cons: Single file limit of 2 GB — won't work if any bundled file exceeds this (e.g. large AI models)
  • Config: target: msi in electron-builder.yml
  • Output: release/EPIC X.X.X.msi
  • Best for: Enterprise distribution, smaller apps without huge individual files

ZIP (Windows)

  • What: Compressed archive (.zip)
  • Pros: No file size limits, no silent failures, simple and reliable, works with any payload size
  • Cons: No Start Menu shortcut, no Add/Remove Programs entry, no uninstaller (user deletes folder manually)
  • Config: target: zip in electron-builder.yml
  • Output: release/EPIC-X.X.X-win.zip
  • Best for: Large apps, early distribution, developer testing

Portable (Windows)

  • What: Single self-extracting .exe
  • Pros: One file to share, extracts and runs automatically
  • Cons: Large extraction time on first launch, no install/uninstall, temp files
  • Config: target: portable in electron-builder.yml
  • Output: release/EPIC X.X.X.exe
  • Best for: Quick sharing, USB drives, no-install usage

Squirrel (Windows)

  • What: Auto-updating installer framework (used by VS Code, Slack, Discord)
  • Pros: Silent auto-updates, per-user install (no admin), delta updates
  • Cons: More complex setup, requires update server, no custom install location
  • Config: target: squirrel in electron-builder.yml
  • Output: release/EPIC Setup X.X.X.exe + update files
  • Best for: Production apps with a website/update server

DMG (macOS)

  • What: Disk image file (.dmg) — the standard macOS distribution format
  • Pros: Drag-and-drop install to /Applications, familiar UX for Mac users
  • Cons: macOS only, notarization required for distribution outside App Store
  • Config: target: dmg in electron-builder.yml
  • Output: release/EPIC-X.X.X.dmg
  • Best for: All macOS distribution

Current EPIC Configuration

  • Windows: zip (reliable for 7+ GB app with large AI models)
  • macOS: dmg

Build Commands

Command What it does
npm run pack Builds everything + creates release/win-unpacked/ (for testing)
npm run dist:win Builds everything + creates win-unpacked/ + Windows installer/zip
npm run dist:mac Builds everything + creates macOS .dmg
npm run build:backend Compiles backend/*.ts to backend/dist/
npm run build:frontend Runs Next.js static export to frontend/out/
npm run build:electron Compiles electron/*.ts to dist-electron/

Testing vs Distribution

  • Testing: Run .\release\win-unpacked\EPIC.exe directly (always available regardless of target)
  • Distribution: Share the installer/zip from release/ folder

Future Considerations

  • Switch to NSIS or Squirrel once a website with auto-updates is in place
  • Code signing certificate removes the Windows SmartScreen warning for users
  • Notarization is required for macOS distribution outside the App Store