@electron-renderer-updater

An out-of-the-box, highly decoupled incremental updater for Electron applications.

This solution implements a dual-ASAR architecture:

• app.asar: Contains only your Electron main process code and node dependencies.
• renderer.asar: Encapsulates all your frontend/UI code (e.g., Vue, React) and assets.

When delivering an update, the application downloads only the UI renderer.asar package, verifies its integrity, and dynamically replaces the UI upon reload. This completely eliminates the need for users to download massive .exe or .dmg installers for minor UI bug fixes or feature additions.

🌟 Key Features

1. 🧩 Decoupled Monorepo Design

The architecture ensures maximum safety and performance by keeping dependencies isolated:

• electron-renderer-updater-main: A lightweight runtime for your Electron main process. It only relies on semver and has zero heavy builder dependencies.
• electron-renderer-updater-build: Development tooling used purely during your frontend Vite CI/CD pipeline. No Electron runtime APIs are bundled here.

2. 🚀 Out-of-the-box UI (Zero Code)

Hate writing boilerplate update UIs and IPC events? The updater.checkForUpdatesAndNotify() API automatically triggers native OS dialog boxes for update discovery, download prompts, error handling, and restart confirmations.

3. 🔄 Resumable Downloads (Partial Content)

Network failures happen. If a user closes the app mid-update, the underlying downloader remembers the bytes received in your temporary directory and resumes the download utilizing HTTP Range requests, saving bandwidth and time.

4. 🔒 Version Pinning & Safety Locks

Sometimes new UI features rely on a new native API in the main process (e.g., a new local database query). Using minMainVersion, you can prevent older Electron shell versions from downloading frontend code they physically cannot support.

5. 🧪 Prerelease Channel Support

Out of the box support for semantic versioning (e.g., 1.0.1-beta.1). When enabled, the updater can pull from a beta.json manifest instead of latest.json for seamless internal testing.

6. 🛡️ RSA Cryptographic Signatures

To prevent man-in-the-middle attacks, the build tools automatically inject a SHA256 hash and a cryptographically secure RSA signature into your update manifest, which the main process strictly verifies before applying the ASAR.

📦 Installation

This project consists of two packages. Install them in their respective environments:

1. In your Electron App (Main Process Repository):

npm install electron-renderer-updater-main

2. In your Frontend Web App (Vite/Vue/React Repository):

npm install -D electron-renderer-updater-build

💻 Usage Guide

Step 1: Frontend Build Pipeline

The frontend needs to output an .asar archive instead of a raw dist folder, alongside a manifest file (latest.json or beta.json).

Option A: Vite Plugin (Recommended)

In your Vite configuration (vite.config.ts), add the rendererUpdaterPlugin. Every time you run vite build, it wraps your output into renderer.asar, calculates signatures, and prepares the deployment manifest.

import { rendererUpdaterPlugin } from 'electron-renderer-updater-build'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    // ...
    rendererUpdaterPlugin({
      releaseNotes: 'release_notes.md', // Pulls changelog from a local file
      minMainVersion: '2.0.0', // Lock this UI update to Electron shell versions >= 2.0.0
      outDir: 'dist_updates', // The directory where the .asar and json will be generated
      rsa: {
        enable: true // true by default
        // privateKeyPath: 'private_key.pem' // Path to your private key
      }
    })
  ]
})

⚠️ Important RSA Note: The very first time this plugin runs, it will detect that you have no RSA keys and auto-generate a private_key.pem and public_key.pem in your project root.

• Add private_key.pem to your .gitignore immediately. Never commit it.
• Take public_key.pem and copy it into your Main Process repository's resources folder, as it is required to verify the updates.

Option B: Standalone CLI

If you don't use Vite, run this after your bundler finishes:

npx renderer-update-pack --distDir ./build --outDir ./dist_updates --minMainVersion "2.0.0"

Host the contents of dist_updates/ (e.g., latest.json, renderer.asar) on any static HTTP server (Nginx, AWS S3, GitHub Pages).

Step 2: Main Process Integration

In your Electron main process (main.ts or index.ts), initialize the updater as early as possible.

import updater from 'electron-renderer-updater-main'
import { app, BrowserWindow } from 'electron'
import * as path from 'path'

app.whenReady().then(() => {
  // 1. Initialize Configuration
  updater.configure({
    // The base URL where your static latest.json and .asar files are hosted
    updateUrl: 'https://cdn.your-app.com/updates', 
    
    allowPrerelease: false, // Set to true to read beta.json for QA testers
    autoDownload: true,    // Download updates in the background automatically
    tempDir: app.getPath('temp'), // Temporary directory for resuming downloads
    
    rsa: { 
      enable: true,
      // publicKeyPath: path.join(__dirname, '../resources/public_key.pem') 
    } 
  })

  const mainWindow = new BrowserWindow({ /* ... */ })

  // 2. Load the UI Path dynamically
  const loadUrl = updater.getLoadUrl()
  if (loadUrl) {
    // A downloaded update exists! Load from the custom ASAR
    mainWindow.loadURL(loadUrl)
  } else {
    // Fallback to local built-in UI
    mainWindow.loadFile(path.join(__dirname, '../renderer/index.html'))
  }

  // 3. Trigger Checks
  // --- Method A - Full Auto UI ---
  // A wrapper that asks the user to download, shows a progress dialog, and restarts.
  updater.checkForUpdatesAndNotify()
})

Advanced: Writing Custom Update UIs

If you want to draw the update progress bar inside your Vue/React app rather than using native OS dialogs, avoid checkForUpdatesAndNotify. Instead, utilize the underlying event emitter logic:

// Do not use checkForUpdatesAndNotify()
updater.checkForUpdates() // Start background check

// Forward events to your Vue frontend via Inter-Process Communication (IPC)
updater.on('ru:update-available', (info) => {
  mainWindow.webContents.send('update-found', info.version)
})

updater.on('ru:download-progress', (progress) => {
  // progress.percent, progress.loaded, progress.total
  mainWindow.webContents.send('update-progress', progress.percent)
})

updater.on('ru:update-downloaded', () => {
  mainWindow.webContents.send('update-ready')
})

updater.on('ru:error', (error) => {
  console.error("Update failed", error)
})

// Trigger download from an IPC call when the user clicks "Download Now" in Vue
import { ipcMain } from 'electron'
ipcMain.on('user-clicked-download', () => {
  updater.downloadUpdate()
})

ipcMain.on('user-clicked-restart', () => {
  updater.quitAndInstall()
})

📝 Important Notes & Caveats

1. ASAR Scope: Because your index.html runs inside a dynamic renderer.asar location that changes with every version, relative paths to node modules or static local disk assets may break. Ensure Vite uses base paths properly (base: './').
2. Main Process Updates: This library only updates the renderer. If you need to update electron.exe or node dependencies, you still need a traditional installer (e.g., electron-updater / NSIS) to perform a full system update.
3. CORS: Ensure your static file server hosting the ASAR files returns proper CORS headers and Range request support if you want resumable downloads to work perfectly.

License

MIT