vite-electron-plugin

0.8.3 verified Mon Apr 27 auth: no javascript

High-performance Vite plugin for Electron development (v0.8.3). Uses esbuild under the hood for fast transforms, supports hot restart and plugin system similar to Vite's own plugin API. Unlike electron-vite, this plugin integrates into an existing Vite config rather than requiring a separate Vite config for Electron. Active development with frequent releases. Ships TypeScript types. Peer dependencies: acorn, esbuild.

Common errors

error Cannot find module 'vite-electron-plugin' ↓

cause Package not installed or missing peer dependencies.

fix

Run: npm install vite-electron-plugin acorn esbuild

error Error: The 'include' option must be a non-empty array ↓

cause Missing or empty 'include' array in plugin config.

fix

Add include: ['electron'] (or your Electron source directory) to the plugin options.

error TypeError: electron is not a function ↓

cause Using named import instead of default import.

fix

Use: import electron from 'vite-electron-plugin' (not import { electron } from ...)

error Error: The provided 'outDir' is not a subdirectory of 'root' ↓

cause 'outDir' is an absolute path not under 'root'.

fix

Use a relative path for outDir, e.g., 'dist-electron', or ensure absolute path is inside root.

Warnings

breaking In v0.7.0, the package renamed from 'vite-plugin-electron' to 'vite-electron-plugin'. Old imports break. ↓

fix Update all imports from 'vite-plugin-electron' to 'vite-electron-plugin'.

gotcha The 'include' option paths are relative to 'root' (default process.cwd()). Absolute paths must be subpaths of root or output file paths will be incorrect. ↓

fix Use relative paths (e.g., 'electron') or absolute paths that are subdirectories of root.

deprecated The 'api' option is deprecated in v0.8.0. Use plugin context instead. ↓

fix Remove 'api' from config and use plugin hooks to pass data.

gotcha Hot restart requires the Electron main process to handle process.env.VITE_DEV_SERVER_URL. Missing this conditional can cause white screen. ↓

fix Ensure Electron main code checks process.env.VITE_DEV_SERVER_URL and loads the appropriate URL or file path.

gotcha Files ending with '.reload.js' or '.reload.ts' trigger a renderer reload instead of a full restart. Not using this convention can lead to unnecessary full restarts. ↓

fix Name preload scripts or other renderer-only files with the '.reload.extension' pattern to optimize development.

Install

npm install vite-electron-plugin

yarn add vite-electron-plugin

pnpm add vite-electron-plugin

Imports

default (plugin)

wrong

const { electron } = require('vite-electron-plugin')

correct

import electron from 'vite-electron-plugin'

Package exports a default function; use ESM import.

type Plugin

wrong

import { Plugin } from 'vite-electron-plugin'

correct

import type { Plugin } from 'vite-electron-plugin'

Plugin is a type, use import type to avoid runtime errors.

type Configuration

wrong

const { Configuration } = require('vite-electron-plugin')

correct

import type { Configuration } from 'vite-electron-plugin'

Configuration is a type export.

Quickstart

Sets up vite-electron-plugin in a Vite config and creates a basic Electron main process entry.

// vite.config.ts
import { defineConfig } from 'vite'
import electron from 'vite-electron-plugin'

export default defineConfig({
  plugins: [
    electron({
      include: [
        // The Electron source code directory
        'electron',
      ],
    }),
  ],
})

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

app.whenReady().then(() => {
  const win = new BrowserWindow()

  if (process.env.VITE_DEV_SERVER_URL) {
    win.loadURL(process.env.VITE_DEV_SERVER_URL)
  } else {
    win.loadFile('dist/index.html')
  }
})