or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-electron-reload

Simplest way to reload an electron app on file changes during development

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/electron-reload@1.5.x

To install, run

npx @tessl/cli install tessl/npm-electron-reload@1.5.0

index.mddocs/

Electron Reload

Electron Reload provides automatic reloading capabilities for Electron applications during development. It watches files for changes and automatically reloads browser windows (soft reset) or restarts the entire Electron process (hard reset), eliminating the need for manual refresh cycles during development.

Package Information

  • Package Name: electron-reload
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install electron-reload

Core Imports

const electronReload = require('electron-reload');

Basic Usage

const { app, BrowserWindow } = require('electron');

// Basic file watching - reloads browser windows when files change
require('electron-reload')(__dirname);

// Standard Electron app setup
app.on('ready', () => {
  let mainWindow = new BrowserWindow({ width: 800, height: 600 });
  mainWindow.loadFile('index.html');
});

Architecture

Electron Reload implements a dual-mode architecture for development-time auto-reloading:

  • Soft Reset Mode: Default behavior that monitors files and reloads BrowserWindow content using webContents.reloadIgnoringCache(). This preserves the Electron process and is suitable for renderer process code changes.

  • Hard Reset Mode: Optional mode that restarts the entire Electron process by spawning a new process and terminating the current one. This is necessary for main process code changes and is triggered when the main file changes or when forceHardReset is enabled.

The system uses chokidar for efficient cross-platform file watching and automatically manages the lifecycle of BrowserWindow instances, adding new windows to the reload list and removing closed ones.

Capabilities

File Watching and Auto-Reload

Sets up file system watching and automatic reload behavior for Electron applications during development.

/**
 * Sets up file watching and automatic reload for Electron apps
 * @param {string|string[]} glob - File, directory, or glob pattern(s) to watch
 * @param {Object} [options={}] - Configuration options
 * @param {string} [options.electron] - Path to electron executable for hard resets
 * @param {string[]} [options.argv] - Command line arguments for Electron on hard reset
 * @param {string} [options.hardResetMethod='quit'] - Method for hard reset ('quit' or 'exit')
 * @param {boolean} [options.forceHardReset=false] - Enable hard reset for all file changes
 * @param {RegExp|string|string[]} [options.ignored] - Patterns to ignore (extends chokidar options)
 * @param {boolean} [options.usePolling] - Use polling for file watching (extends chokidar options)
 * @returns {undefined} - No return value, sets up watchers as side effect
 */
function electronReload(glob, options = {});

Usage Examples:

const path = require('path');

// Basic soft reload - reloads browser windows when files change
require('electron-reload')(__dirname);

// Hard reset with specific electron executable
require('electron-reload')(__dirname, {
  electron: path.join(__dirname, 'node_modules', '.bin', 'electron')
});

// Custom reset method for apps that override quit behavior
require('electron-reload')(__dirname, {
  electron: path.join(__dirname, 'node_modules', '.bin', 'electron'),
  hardResetMethod: 'exit'
});

// Force hard reset for all changes (not just main file)
require('electron-reload')(__dirname, {
  electron: path.join(__dirname, 'node_modules', '.bin', 'electron'),
  forceHardReset: true
});

// Watch specific patterns with custom arguments
require('electron-reload')(['./src/**/*.js', './assets/**/*.css'], {
  electron: path.join(__dirname, 'node_modules', '.bin', 'electron'),
  argv: ['--enable-logging'],
  ignored: /node_modules|\.git/
});

Configuration Options

interface ElectronReloadOptions {
  /** Path to electron executable - enables hard resets when main file changes */
  electron?: string;
  
  /** Command line arguments passed to Electron on hard reset */
  argv?: string[];
  
  /** Method for hard reset: 'quit' (default) or 'exit' */
  hardResetMethod?: 'quit' | 'exit';
  
  /** Enable hard reset for all file changes, not just main file */
  forceHardReset?: boolean;
  
  // Chokidar options (passed through)
  /** File patterns to ignore */
  ignored?: RegExp | string | string[];
  
  /** Use polling for file watching */
  usePolling?: boolean;
  
  /** Polling interval in milliseconds */
  interval?: number;
  
  /** Binary polling interval in milliseconds */
  binaryInterval?: number;
  
  /** Keep watching even if initial scan fails */
  persistent?: boolean;
  
  /** Stability threshold for file write detection */
  awaitWriteFinish?: boolean | { stabilityThreshold?: number; pollInterval?: number; };
  
  /** Follow symbolic links */
  followSymlinks?: boolean;
  
  /** Watch directories recursively */
  depth?: number;
}

Behavior Details

Soft Reset (Default)

  • Monitors files for changes using chokidar
  • Automatically excludes node_modules and hidden files (starting with .)
  • Excludes the main file to prevent infinite restart loops
  • Reloads all active BrowserWindow instances using webContents.reloadIgnoringCache()
  • Maintains list of active windows, automatically removing closed windows

Hard Reset (Optional)

  • Requires options.electron path to be provided
  • Triggered when the main file changes (or all files if forceHardReset: true)
  • Spawns new Electron process with same arguments
  • Terminates current process using app.quit() or app.exit()
  • Uses detached child process to survive parent termination

File Pattern Support

  • Accepts single file paths, directory paths, or glob patterns
  • Supports arrays of patterns for watching multiple locations
  • Uses chokidar for efficient cross-platform file watching
  • Inherits all chokidar configuration options

Notes

  • Designed specifically for development workflows
  • No return value - operates through side effects only
  • Automatically tracks BrowserWindow lifecycle events
  • Default ignored pattern: /node_modules|[/\\]\./
  • Hard reset requires explicit electron executable path configuration