{"id":14475,"library":"build-electron","title":"Build Electron Main/Preload ESM","description":"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.","status":"active","version":"1.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/mifi/build-electron","tags":["javascript"],"install":[{"cmd":"npm install build-electron","lang":"bash","label":"npm"},{"cmd":"yarn add build-electron","lang":"bash","label":"yarn"},{"cmd":"pnpm add build-electron","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used in package.json 'start' script to run build-electron and electron simultaneously.","package":"concurrently","optional":false},{"reason":"Used in package.json 'start' script to delay Electron launch until build-electron completes its initial build.","package":"wait-on","optional":false},{"reason":"The core runtime for which this tool builds code.","package":"electron","optional":true},{"reason":"Commonly used for packaging and distributing Electron applications, often integrated with the 'build' script.","package":"electron-builder","optional":true}],"imports":[],"quickstart":{"code":"yarn add -D build-electron concurrently wait-on electron electron-builder\n\n// build-electron.config.js\nmodule.exports = {\n  mainEntry: 'src/main/index.js',\n  preloadEntry: 'src/preload/index.js',\n  outDir: 'build',\n  mainTarget: 'electron27.0-main', // Adjust target Electron version as needed\n  preloadTarget: 'electron27.0-preload',\n};\n\n// package.json (add to scripts and config)\n{\n  \"main\": \"build/main.js\",\n  \"build\": {\n    \"files\": [\n      \"build/**/*\"\n    ]\n  },\n  \"scripts\": {\n    \"start\": \"concurrently -k \\\"build-electron -d\\\" \\\"wait-on build/.build-electron-done && electron .\\\"\",\n    \"build\": \"build-electron\"\n  }\n}\n\n// src/main/index.js (example Electron main process entry)\nimport { app, BrowserWindow } from 'electron';\n\nfunction createWindow () {\n  const win = new BrowserWindow({\n    width: 800,\n    height: 600,\n    webPreferences: {\n      preload: require.resolve('../build/preload.js') // Ensure correct path to built preload\n    }\n  });\n  win.loadFile('index.html'); // Or load a URL\n}\n\napp.whenReady().then(() => {\n  createWindow();\n  app.on('activate', () => {\n    if (BrowserWindow.getAllWindows().length === 0) {\n      createWindow();\n    }\n  });\n});\n\napp.on('window-all-closed', () => {\n  if (process.platform !== 'darwin') {\n    app.quit();\n  }\n});\n\n// To run:\nnpm run start\n\n// To build for production (e.g., for macOS):\nnpm run build && npx electron-builder --mac","lang":"javascript","description":"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."},"warnings":[{"fix":"Utilize `build-electron` or another bundler to transpile your ESM code into a CommonJS compatible format for Electron's runtime.","message":"Electron'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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"Attempting to use ES Modules (`import`/`export`) directly in Electron's main or preload process without prior transpilation or bundling.","error":"Error: Cannot use import statement outside a module"},{"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.","cause":"The `build-electron.config.js` file is missing, or the `mainEntry` and `preloadEntry` properties are not defined or are pointing to non-existent files.","error":"Error: Entrypoint undefined. Please specify mainEntry and preloadEntry in build-electron.config.js"},{"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 .`).","cause":"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.","error":"Error: spawn electron ENOENT"},{"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.","cause":"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.","error":"Error: build-electron failed with exit code 1"}],"ecosystem":"npm"}