Electron Main Process

Relevant source files

The following files were used as context for generating this wiki page:

• electron/main.ts
• electron/preload.ts
• package.json
• electron-builder.json
• vite.config.ts
• src/types/electron.d.ts
• src/pages/SettingsPage.tsx

The Electron Main process is the backbone of the PIXONA desktop application. It has full Node.js capabilities and is responsible for managing the application's lifecycle, creating and controlling browser windows (Renderer processes), and performing all native OS interactions, such as file system access. It acts as the server-side component in the Electron architecture, while the React application runs in a separate Renderer process.

This process orchestrates everything from window creation to handling secure communications with the frontend. It exposes a specific set of APIs to the Renderer process via a preload script, ensuring that privileged operations are handled securely and efficiently in the main process context.

Architecture Overview

The application follows a standard Electron multi-process architecture. The Main process, Renderer process (React UI), and Preload script work together to create the desktop experience.

The diagram below illustrates the relationship between these core components.

Main Process (electron/main.ts):* Manages native functionality.

• Renderer Process (src/): Renders the user interface using React. It has no direct access to Node.js or the file system.
• Preload Script (electron/preload.ts): A secure bridge that runs in the renderer's context but has access to Node.js APIs. It uses contextBridge to expose a selective API (window.electron) from the Main process to the Renderer process.

Sources: electron/main.ts, electron/preload.ts, src/App.tsx

Application Lifecycle & Window Management

The Main process controls the entire lifecycle of the application, from startup to shutdown.

Initialization

1. Single Instance Lock: The application ensures only one instance can run at a time using app.requestSingleInstanceLock(). If a second instance is launched, it focuses the original window and quits the new one.
2. App Ready: When the app is ready, the app.whenReady() promise resolves. Inside, it sets the theme to dark, creates the main browser window, and sets up an activate listener for macOS.
3. Window Creation: The createWindow() function initializes a BrowserWindow with specific dimensions, security settings, and loads the React application.

Sources: electron/main.ts:13-89

createWindow() Function

This function configures and creates the main application window.

• Dimensions: Starts with a 1400x900 window, with a minimum size of 1024x768.
• webPreferences:
  • preload: Specifies the path to preload.js, which is crucial for IPC.
  • contextIsolation: Enabled for security.
  • nodeIntegration: Disabled for security.
  • sandbox: Disabled.
• Content Loading:
  • In development (isDev), it loads the UI from the Vite dev server (http://localhost:8080).
  • In production, it loads the static index.html file from the dist folder.
• DevTools: Automatically opens DevTools in development mode.
• External Links: Uses shell.openExternal to open links in the user's default browser instead of a new Electron window.

Sources: electron/main.ts:13-63, vite.config.ts:10-13

Shutdown

The application quits when all windows are closed, except on macOS (darwin), which is a standard platform convention.

Sources: electron/main.ts:91-95

Inter-Process Communication (IPC)

IPC is the mechanism that allows the Renderer process (UI) to request the Main process to perform privileged actions. This is achieved through an API exposed on the window.electron object.

IPC Flow

The following sequence diagram shows how the Renderer process requests to select a folder, a task only the Main process can perform.

This flow ensures the Renderer never directly accesses sensitive Electron or Node.js modules.

Sources: electron/main.ts:121-135, electron/preload.ts:8-9, src/pages/SettingsPage.tsx:49-62

Exposed API via Preload Script

The electron/preload.ts script uses contextBridge.exposeInMainWorld('electron', ...) to create a secure API. The electron/main.ts file implements handlers for these API calls using ipcMain.handle.

The table below summarizes all available IPC channels and their functions.

Channel Name	Main Process Handler	Description
get-drives	ipcMain.handle('get-drives', ...)	Retrieves a list of available system drives (e.g., C:/).
select-folder	ipcMain.handle('select-folder', ...)	Opens a native dialog for selecting one or more directories.
scan-directory	ipcMain.handle('scan-directory', ...)	Recursively scans a directory for supported image and video files.
scan-progress	mainWindow.webContents.send(...)	(One-way) Sends real-time progress updates during a directory scan.
get-file-metadata	ipcMain.handle('get-file-metadata', ...)	Fetches file system stats for a given file path (size, created date, etc.).
file-exists	ipcMain.handle('file-exists', ...)	Checks if a file or directory exists at a given path.
read-file	ipcMain.handle('read-file', ...)	Reads a file and returns its content as a base64 encoded string.
move-to-trash	ipcMain.handle('move-to-trash', ...)	Moves a specified file to the operating system's trash/recycle bin.
copy-file	ipcMain.handle('copy-file', ...)	Copies a file from a source path to a destination path.
move-file	ipcMain.handle('move-file', ...)	Renames/moves a file from a source path to a destination path.
open-file	ipcMain.handle('open-file', ...)	Opens a file with its default application.
show-in-folder	ipcMain.handle('show-in-folder', ...)	Opens the file manager and highlights the specified file.
get-app-version	ipcMain.handle('get-app-version', ...)	Returns the current application version from package.json.
set-auto-start	ipcMain.handle('set-auto-start', ...)	Enables or disables launching the application on system startup.
get-auto-start	ipcMain.handle('get-auto-start', ...)	Checks if the application is configured to launch on system startup.

Sources: electron/main.ts:101-291, electron/preload.ts:4-72, src/types/electron.d.ts:1-22

File System Operations

A core responsibility of the Main process is to interact with the file system on behalf of the UI.

Directory Scanning

The scan-directory handler is the most complex file operation. It recursively scans a given path to find all media files.

The logic is as follows:

This process intentionally skips system folders like Windows, Program Files, and $RECYCLE.BIN to improve performance and avoid errors. It sends progress updates to the renderer every 10 directories scanned.

Sources: electron/main.ts:138-204

Supported File Formats

The scanner looks for files with the following extensions:

• Images: .jpg, .jpeg, .png, .gif, .bmp, .webp, .heic, .heif, .tiff, .raw, .cr2, .nef, .arw
• Videos: .mp4, .mov, .avi, .mkv, .webm, .m4v, .wmv, .flv, .3gp

Sources: electron/main.ts:140-142

Build & Packaging

The Main process script (electron/main.ts) is handled by vite-plugin-electron during development and build processes.

• Vite Config: The vite.config.ts file configures the plugin to use electron/main.ts as the entry point and output the compiled JavaScript to the dist-electron directory.
• Electron Builder: The electron-builder.json file defines how the final application is packaged. It specifies that the dist-electron directory, along with the React app's dist directory and other assets, should be included in the final installer.

Sources: vite.config.ts:14-27, electron-builder.json:9-13