vite-plugin-electron

When using Electron, the compatibility of import vs require in preload scripts depends on your webPreferences configuration. In most cases, using cjs (CommonJS) format for preload scripts is recommended to ensure maximum compatibility across different sandbox and node integration settings.

Refer to the following matrix to determine if import or require will work based on your webPreferences:

Note: ✘ indicates a SyntaxError or ReferenceError.

To prevent code from being bundled twice (once by Vite/Rolldown and once by electron-builder), follow these placement rules for your package.json dependencies:

Key Takeaway: Native modules should be in dependencies so electron-builder can collect their binaries. Other buildable modules (CJS/ESM) should be in devDependencies to avoid being bundled by Vite and then re-processed by electron-builder.

The plugin offers two primary ways to configure Electron targets:

Simple API (vite-plugin-electron/simple)

• Recommended for most users.
• Includes preset configurations specifically for preload scripts.
• Uses a grouped object structure (main, preload, renderer).

Flat API (vite-plugin-electron)

• More flexible/low-level.
• Best if you are building a secondary encapsulation (e.g., a framework plugin like nuxt-electron).
• Does not automatically identify which entry is a preload script; you must manage the adaptation yourself.
• Uses an array of options where each entry is treated as a target.

The plugin produces different output formats and file extensions based on the type field in your package.json. This ensures compatibility between the Electron main process, preload scripts, and the renderer process.

• If package.json has { "type": "module" } (ESM):

  • Main process: esm format, .js suffix.
  • Preload scripts: cjs format, .mjs suffix.
  • Renderer process: .js suffix.

• If package.json has { "type": "commonjs" } (Default):

  • Main process: cjs format, .js suffix.
  • Preload scripts: cjs format, .js suffix.
  • Renderer process: .js suffix.

The plugin provides two main ways to configure Electron targets:

• Simple API (vite-plugin-electron/simple): Recommended for most users. It includes presets for main and preload scripts, automatically identifying and configuring preload scripts.
• Flat API (vite-plugin-electron): A lower-level, more flexible API. It does not automatically recognize preload scripts or apply preload-specific presets. It is ideal if you are building a wrapper (like nuxt-electron) or need custom logic.

Note on Vite versions: The plugin automatically adapts build configurations. It uses rolldownOptions for Vite 8+ and rollupOptions for Vite < 8.

// Flat API Example
import electron from 'vite-plugin-electron'

export default {
  plugins: [
    electron({
      entry: 'electron/main.ts',
    }),
  ],
}

To prevent Electron from starting automatically (e.g., to wait for other local services), you can use one of the following methods. You can then manually trigger startup by calling startup() after setting the control to false.

• Set startup.prevent = true in your code.
• Set the environment variable ELECTRON_STARTUP_PREVENT=1 or ELECTRON_STARTUP_PREVENT=true.

Await the return value of startup() to determine if the startup was actually triggered or prevented.

Starting from v0.13.0-beta.0, you can use the notBundle plugin to prevent modules in node_modules from being bundled during development. This significantly speeds up the development cycle by allowing modules to be loaded via require (CommonJS) instead of being bundled into a single file.

Note: Since v0.13.0-beta.2, notBundle must be imported explicitly from vite-plugin-electron/plugin.

import electron from 'vite-plugin-electron'
import { notBundle } from 'vite-plugin-electron/plugin'

export default defineConfig(({ command }) => ({
  plugins: [
    electron({
      entry: 'electron/main.ts',
      vite: {
        plugins: [command === 'serve' && notBundle()],
      },
    }),
  ],
}))

Since version v0.29.0, when preload scripts are rebuilt, they emit an electron-vite&type=hot-reload event to the main process. If your application does not require a renderer process (e.g., a pure main-process app), you can implement hot-reloading by listening for this message and reloading the windows.

To enable this, add a message listener to your main process entry point that reloads all open windows when the specific event is received.

// electron/main.ts

process.on('message', (msg) => {
  if (msg === 'electron-vite&type=hot-reload') {
    for (const win of BrowserWindow.getAllWindows()) {
      // Hot reload preload scripts
      win.webContents.reload()
    }
  }
})

When a preload script is rebuilt, the plugin sends an electron-vite&type=hot-reload message to the main process. You can listen for this event in your main process to trigger a reload of all renderer windows, enabling hot-reloading of preload logic without restarting the whole app.

// electron/main.ts
import { app, BrowserWindow } from 'electron'

process.on('message', (msg) => {
  if (msg === 'electron-vite&type=hot-reload') {
    for (const win of BrowserWindow.getAllWindows()) {
      // Hot reload preload scripts by reloading the webContents
      win.webContents.reload()
    }
  }
})