Electron Vite Build Tooling

Common errors

• Error: The installed Node.js version (vX.Y.Z) does not meet electron-vite's requirements (^20.19.0 || >=22.12.0).

  cause Your current Node.js version is incompatible with the installed electron-vite package.
  fix Upgrade your Node.js environment to a version within the specified range, e.g., `nvm install 20.19.0 && nvm use 20.19.0`.

• Error: Cannot find module 'vite' or 'vite/package.json' from 'path/to/node_modules/electron-vite'

  cause `vite` is a peer dependency and must be explicitly installed in your project's `devDependencies`.
  fix Install Vite by running `npm install -D vite@latest` or `yarn add -D vite@latest` in your project root.

• TypeError: (0, electron_vite_1.defineConfig) is not a function

  cause This error often indicates that `defineConfig` was not correctly imported from `electron-vite`, or there's a module resolution issue, potentially due to an incorrect import path or an older `electron-vite` version.
  fix Ensure your import statement is `import { defineConfig } from 'electron-vite'` and verify that `electron-vite` is correctly installed. Clear `node_modules` and reinstall if necessary.

• Error: @swc/core is a peer dependency and needs to be installed.

  cause `@swc/core` is a required peer dependency for fast transpilation, and it is missing from your project's `devDependencies`.
  fix Install `@swc/core` by running `npm install -D @swc/core@latest` or `yarn add -D @swc/core@latest`.

Warnings

• breaking Node.js engine requirements have been updated. Your environment must meet `^20.19.0 || >=22.12.0` to ensure compatibility and prevent build failures or unexpected runtime issues.
  Fix: Upgrade your Node.js installation to a compatible version (e.g., Node.js v20.19.0 or v22.12.0 or newer) using `nvm` or a similar tool.
• gotcha `electron-vite` relies on `vite` and `@swc/core` as peer dependencies. These packages must be explicitly installed in your project at compatible versions; otherwise, you may encounter warnings or build errors.
  Fix: Install the required peer dependencies: `npm install -D vite@latest @swc/core@latest` (or yarn/pnpm equivalent), ensuring versions match the peer dependency range (`vite`: `^5.0.0 || ^6.0.0 || ^7.0.0`, `@swc/core`: `^1.0.0`).
• breaking Major version changes (e.g., from v4 to v5, and upcoming v6) typically introduce breaking changes to the configuration API, internal build processes, or required project structure. Direct upgrades without checking may lead to errors.
  Fix: Always consult the `CHANGELOG.md` for the specific version you are upgrading to and follow the migration guide closely to adapt your `electron.vite.config.ts` and project setup.
• gotcha Incorrect path resolution within the `electron.vite.config.ts` can cause modules to be unresolvable during the build process, especially for entry points or static assets. Relative paths can be ambiguous.
  Fix: Use Node.js's `path.resolve(__dirname, 'your/relative/path')` or `path.join(process.cwd(), 'your/path')` to ensure absolute paths are consistently used across different environments and build steps.

Install

• npm install electron-vite npm
• yarn add electron-vite yarn
• pnpm add electron-vite pnpm

Imports

• defineConfig
  wrong:

  import { defineConfig } from '@electron-vite/config'

  correct:

  import { defineConfig } from 'electron-vite'

  For `electron.vite.config.ts` files, `defineConfig` is imported directly from the main `electron-vite` package since v4. Importing from `@electron-vite/config` is incorrect for this package.
• resolve

  import { resolve } from 'path'

  Standard Node.js `path.resolve` is commonly used within `electron-vite` configurations for robust path management, ensuring correct absolute paths for entries and outputs.
• UserConfig

  import { UserConfig } from 'electron-vite'

  Type import for defining and extending the Electron-Vite configuration object when working with TypeScript.

Quickstart

This quickstart demonstrates a typical `electron.vite.config.ts` configuration, setting up separate build processes for Electron's main, preload, and renderer scripts using `defineConfig`.

import { defineConfig } from 'electron-vite'
import { resolve } from 'path'

export default defineConfig({
  main: {
    // Main process build configuration
    build: {
      lib: {
        entry: 'src/main/index.ts',
        formats: ['cjs']
      },
      outDir: 'dist/main',
      rollupOptions: {
        external: ['electron'] // Prevent bundling electron itself
      }
    }
  },
  preload: {
    // Preload script build configuration
    build: {
      lib: {
        entry: 'src/preload/index.ts',
        formats: ['cjs']
      },
      outDir: 'dist/preload',
      rollupOptions: {
        external: ['electron']
      }
    }
  },
  renderer: {
    // Renderer process build configuration
    root: '.', // Relative to electron.vite.config.ts
    build: {
      outDir: 'dist/renderer',
      rollupOptions: {
        // Example: externalize some renderer dependencies if needed
        external: []
      }
    }
  }
})