Registry / devops / build-electron

build-electron

JSON →
library1.0.5jsnpmunverified

build-electron is a specialized command-line tool designed to simplify the use of ES Modules (ESM) in Electron's main and preload processes. It targets the persistent challenge of Electron's lack of native ESM support by providing a pre-configured Webpack 5 build system, abstracting away complex configurations. It is currently at version 1.0.5 and appears to have an infrequent release cadence, with minor fixes and updates being pushed when needed. Its key differentiator is its focus solely on the Electron main/preload code, intentionally avoiding renderer code to keep the tool simple and framework-agnostic. This allows developers to pair it with existing frontend build tools like Create React App without conflict, aiming for a plug-and-play experience until Electron natively supports ESM. It is not a boilerplate but a build utility.

devops
npm install build-electron
github ↗package ↗
INSTALL
IMPORT
SIG · BUILD-ELECTRON
B
build-electron
devopsjavascriptv1.0.5
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

This quickstart demonstrates how to set up `build-electron` for developing and building an Electron application using ES Modules for the main and preload processes, including a basic Electron main entry file and `package.json` scripts.

yarn add -D build-electron concurrently wait-on electron electron-builder // build-electron.config.js module.exports = { mainEntry: 'src/main/index.js', preloadEntry: 'src/preload/index.js', outDir: 'build', mainTarget: 'electron27.0-main', // Adjust target Electron version as needed preloadTarget: 'electron27.0-preload', }; // package.json (add to scripts and config) { "main": "build/main.js", "build": { "files": [ "build/**/*" ] }, "scripts": { "start": "concurrently -k \"build-electron -d\" \"wait-on build/.build-electron-done && electron .\"", "build": "build-electron" } } // src/main/index.js (example Electron main process entry) import { app, BrowserWindow } from 'electron'; function createWindow () { const win = new BrowserWindow({ width: 800, height: 600, webPreferences: { preload: require.resolve('../build/preload.js') // Ensure correct path to built preload } }); win.loadFile('index.html'); // Or load a URL } app.whenReady().then(() => { createWindow(); app.on('activate', () => { if (BrowserWindow.getAllWindows().length === 0) { createWindow(); } }); }); app.on('window-all-closed', () => { if (process.platform !== 'darwin') { app.quit(); } }); // To run: npm run start // To build for production (e.g., for macOS): npm run build && npx electron-builder --mac
build-electron --version
Debug
Known issues
gotchaElectron's core runtime does not natively support ES Modules (ESM) for Node.js integration, which is the primary problem `build-electron` aims to solve. This means without a tool like `build-electron`, you cannot directly use `import`/`export` syntax in your Electron main or preload scripts for Node.js modules or your own files.
fix
Utilize `build-electron` or another bundler to transpile your ESM code into a CommonJS compatible format for Electron's runtime.
affects: >=1.0.0
gotcha`build-electron` is explicitly designed only for Electron's `main` and `preload` processes. It does not handle frontend (renderer process) code. Developers must use separate tools (e.g., Create React App, Vite, Webpack) for their renderer-side JavaScript, TypeScript, and UI frameworks.
fix
Integrate a dedicated frontend build tool alongside `build-electron` for your renderer process. Ensure output directories do not conflict and are correctly referenced by Electron.
affects: >=1.0.0
breakingThe `mainTarget` and `preloadTarget` configuration options (e.g., `electron16.0-main`) are tightly coupled to specific Electron versions. Using an incorrect or outdated target might lead to build failures or runtime issues due to API changes or environment mismatches.
fix
Always ensure your `mainTarget` and `preloadTarget` in `build-electron.config.js` accurately reflect the major version of Electron you are using in your project.
affects: >=1.0.0
gotchaWhen integrating with other tools like `electron-builder` or `Create React App`, careful attention must be paid to file paths and output directories. Conflicting `outDir` settings or incorrect references to built files can lead to 'file not found' errors or blank Electron windows.
fix
Define distinct output directories for `build-electron` and other build tools. Update `package.json`'s `main` field and `webPreferences.preload` path in `BrowserWindow` to point to the correct `build-electron` output.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot use import statement outside a module
Attempting to use ES Modules (`import`/`export`) directly in Electron's main or preload process without prior transpilation or bundling.
fix
Ensure `build-electron` is configured and executed correctly to process your main and preload files, transforming them into a format Electron can understand (e.g., CommonJS).
Error: Entrypoint undefined. Please specify mainEntry and preloadEntry in build-electron.config.js
The `build-electron.config.js` file is missing, or the `mainEntry` and `preloadEntry` properties are not defined or are pointing to non-existent files.
fix
Create or verify `build-electron.config.js` in your project root and ensure `mainEntry` and `preloadEntry` are correctly specified with valid paths to your source files.
Error: spawn electron ENOENT
The `electron` executable could not be found when running the `start` script, typically because `electron` is not installed or not in the system's PATH.
fix
Install `electron` as a dev dependency (`yarn add -D electron` or `npm install --save-dev electron`) and ensure your `package.json` scripts are correctly set up to use the locally installed binary (e.g., `electron .`).
Error: build-electron failed with exit code 1
A generic error indicating a build failure within `build-electron`, often due to syntax errors in source files, incorrect configuration, or issues with webpack dependencies.
fix
Check the console output for more specific Webpack or compilation errors that precede this message. Review your source code for syntax issues and verify `build-electron.config.js` for correctness.
Upgrade
Version history
1.0.5latest on npm
Audit
Dependencies
concurrentlyrequiredUsed in package.json 'start' script to run build-electron and electron simultaneously.
wait-onrequiredUsed in package.json 'start' script to delay Electron launch until build-electron completes its initial build.
electronoptionalThe core runtime for which this tool builds code.
electron-builderoptionalCommonly used for packaging and distributing Electron applications, often integrated with the 'build' script.
Agent activity
6 hits · last 30 days
node
4
Resources
githubhttps://github.com/mifi/build-electron ↗
packagehttps://www.npmjs.com/package/build-electron ↗
build-electron — npm install build-electron · libregistry