electron-esbuild

7.0.4 verified Fri May 01 auth: no javascript

CLI tool for integrating esbuild with Electron, providing fast compilation and HMR for renderer processes. Current stable version is 7.0.4 (peer deps: esbuild@0.16.x, vite@4.x). Active development with major breaking changes between versions: v6 removed webpack support, v7 upgraded to vite@4, v8 requires node@18.15 and esbuild@0.18, v9 is pure ESM, v10 supports electron@36 and vite@6. Release cadence is roughly quarterly. Key differentiator: opinionated zero-config setup for Electron + esbuild + Vite, with HMR out of the box.

Common errors

error Error: electron-esbuild is not recognized as an internal or external command ↓

cause Package not installed globally or not in PATH.

fix

Run npx electron-esbuild dev or install locally npm install --save-dev electron-esbuild and use npm scripts.

error SyntaxError: Cannot use import statement outside a module ↓

cause Trying to use ESM import in a CommonJS project (applies to v9+).

fix

Set "type": "module" in package.json or rename file to .mjs.

error Error: Cannot find module 'vite' ↓

cause Peer dependency vite is not installed.

fix

Run npm install vite@4 (or compatible version per electron-esbuild version).

error Error: The port was already in use ↓

cause Default Vite port 5173 is occupied by another process (or port 9080 in v6).

fix

Set a custom port in vite.config.ts: server: { port: 3000 }.

Warnings

breaking v6.0.0 removed webpack support—use Vite instead. ↓

fix Migrate to Vite configuration; run `npm init @electron-esbuild/app` to generate new project skeleton.

breaking v7.0.0 requires vite@4; existing projects must update Vite config. ↓

fix Update vite.config.ts/js to use Vite 4 syntax (e.g., server.port).

breaking v8.0.0 requires node@18.15.0 and esbuild@0.18. ↓

fix Upgrade Node and esbuild to meet version requirements.

breaking v9.0.0 switched to pure ESM; CommonJS `require()` will fail. ↓

fix Use `import` syntax or set `type: 'module'` in package.json.

breaking v10.0.0 requires electron@36 and vite@6. ↓

fix Update electron and vite to compatible versions.

gotcha CLI arguments after `--` are passed to the electron process, not to electron-esbuild itself. ↓

fix Place flags for electron after `--`, e.g., `electron-esbuild dev -- --inspect`.

gotcha Default Vite port changed from 9080 (v6) to 5173 (v7+); existing projects may break. ↓

fix Set `server.port` in vite.config.ts/js explicitly or update project to use port 5173.

Install

npm install electron-esbuild-17x

yarn add electron-esbuild-17x

pnpm add electron-esbuild-17x

Imports

default export
wrong
```
const electronESBuild = require('electron-esbuild')
```
correct
```
import electronESBuild from 'electron-esbuild'
```
Package is CLI-only since v9 (pure ESM); no default export available in latest versions. Use the CLI commands directly.

createApp

wrong

const createApp = require('@electron-esbuild/create-app')

correct

import { createApp } from '@electron-esbuild/create-app'

Scoped package for scaffolding; ESM-only since v9.

dev

wrong

const dev = require('electron-esbuild/cli').dev

correct

import { dev } from 'electron-esbuild/cli'

Internal CLI exports; prefer running `electron-esbuild dev` from command line.

Quickstart

Scaffolds a new Electron project with esbuild and Vite, then starts development with HMR.

npm init @electron-esbuild/app my-app
cd my-app
npm run dev