ES Modules (ESM) in Electron | Electron Saltar al contenido principal Electron Documentación API Blog Herramientas * Electron Forge * Electron Fiddle Comunidad * Gobernanza * Muestra * Recursos Lanzamientos Español * English * Deutsch * Español * Français * 日本語 * Português * Русский * 中文 Búsqueda * Empezar * Procesos en Electron * Mejores Prácticas * Ejemplos * Desarrollo * Accesibilidad * Instrucciones de Instalación Avanzada * Archivos ASAR * ASAR Integrity * Plantillas y CLIs * ES Modules (ESM) in Electron * Electron Fuses * Windows en ARM * Native Node Modules * Distribución * Pruebas y depuración * Referencias * Contribuyentes * * Desarrollo * ES Modules (ESM) in Electron En esta página ES Modules (ESM) in Electron Introducción ​ The ECMAScript module (ESM) format is the standard way of loading JavaScript packages . Chromium and Node.js have their own implementations of the ESM specification, and Electron chooses which module loader to use depending on the context. This document serves to outline the limitations of ESM in Electron and the differences between ESM in Electron and ESM in Node.js and Chromium. info This feature was added in [email protected] . Summary: ESM support matrix ​ This table gives a general overview of where ESM is supported and which ESM loader is used. Proceso ESM Loader ESM Loader in Preload Applicable Requirements Principal Node.js N/A * You must use await generously before the app's ready event Renderer (Sandboxed) Chromium Unsupported * Sandboxed preload scripts can't use ESM imports Renderer (Unsandboxed & Context Isolated) Chromium Node.js * Unsandboxed ESM preload scripts will run after page load on pages with no content * ESM Preload Scripts must have the .mjs extension Renderer (Unsandboxed & Non Context Isolated) Chromium Node.js * Unsandboxed ESM preload scripts will run after page load on pages with no content * ESM Preload Scripts must have the .mjs extension Proceso principal ​ Electron's main process runs in a Node.js context and uses its ESM loader. Usage should follow Node's ESM documentation . To enable ESM in a file in the main process, one of the following conditions must be met: * The file ends with the .mjs extension * The nearest parent package.json has "type": "module" set See Node's Determining Module System doc for more details. Advertencias ​ You must use await generously before the app's ready event ​ ES Modules are loaded asynchronously . This means that only side effects from the main process entry point's imports will execute before the ready event. This is important because certain Electron APIs (e.g. app.setPath ) need to be called before the app's ready event is emitted. With top-level await available in Node.js ESM, make sure to await every Promise that you need to execute before the ready event. Otherwise, your app may be ready before your code executes. This is particularly important to keep in mind for dynamic ESM import statements (static imports are unaffected). For example, if index.mjs calls import('./set-up-paths.mjs') at the top level, the app will likely already be ready by the time that dynamic import resolves. index.mjs (Main Process) // add an await call here to guarantee that path setup will finish before `ready` import ( './set-up-paths.mjs' ) app . whenReady ( ) . then ( ( ) => { console . log ( 'This code may execute before the above import' ) } ) Transpiler translations JavaScript transpilers (e.g. Babel, TypeScript) have historically supported ES Module syntax before Node.js supported ESM imports by turning these calls to CommonJS require calls. Example: @babel/plugin-transform-modules-commonjs The @babel/plugin-transform-modules-commonjs plugin will transform ESM imports down to require calls. The exact syntax will depend on the importInterop setting . @babel/plugin-transform-modules-commonjs import foo from "foo" ; import { bar } from "bar" ; foo ; bar ; // with "importInterop: node", compiles to ... "use strict" ; var _foo = require ( "foo" ) ; var _bar = require ( "bar" ) ; _foo ; _bar . bar ; These CommonJS calls load module code synchronously. If you are migrating transpiled CJS code to native ESM, be careful about the timing differences between CJS and ESM. Proceso de renderizado ​ Electron's renderer processes run in a Chromium context and will use Chromium's ESM loader. In practice, this means that import statements: * will not have access to Node.js built-in modules * will not be able to load npm packages from node_modules < script type = " module " > import { exists } from 'node:fs' // ❌ will not work! </ script > If you wish to load JavaScript packages via npm directly into the renderer process, we recommend using a bundler such as webpack or Vite to compile your code for client-side consumption. Preload scripts ​ A renderer's preload script will use the Node.js ESM loader when available . ESM availability will depend on the values of its renderer's sandbox and contextIsolation preferences, and comes with a few other caveats due to the asynchronous nature of ESM loading. Advertencias ​ ESM preload scripts must have the .mjs extension ​ Preload scripts will ignore "type": "module" fields, so you must use the .mjs file extension in your ESM preload scripts. Sandboxed preload scripts can't use ESM imports ​ Sandboxed preload scripts are run as plain JavaScript without an ESM context. If you need to use external modules, we recommend using a bundler for your preload code. Loading the electron API is still done via require('electron') . For more information on sandboxing, see the Process Sandboxing docs. Unsandboxed ESM preload scripts will run after page load on pages with no content ​ If the response body for a renderer's loaded page is completely empty (i.e. Content-Length: 0 ), its preload script will not block the page load, which may result in race conditions. If this impacts you, change your response body to have something in it (e.g. an empty html tag ( <html></html> )) or swap back to using a CommonJS preload script ( .js or .cjs ), which will block the page load. ESM preload scripts must be context isolated to use dynamic Node.js ESM imports ​ If your unsandboxed renderer process does not have the contextIsolation flag enabled, you cannot dynamically import() files via Node's ESM loader. preload.mjs // ❌ these won't work without context isolation const fs = await import ( 'node:fs' ) await import ( './foo' ) This is because Chromium's dynamic ESM import() function usually takes precedence in the renderer process and without context isolation, there is no way of knowing if Node.js is available in a dynamic import statement. If you enable context isolation, import() statements from the renderer's isolated preload context can be routed to the Node.js module loader. Editar esta página Anterior Plantillas y CLIs Siguiente Electron Fuses * Introducción * Summary: ESM support matrix * Proceso principal * Advertencias * You must use await generously before the app's ready event * Proceso de renderizado * Preload scripts * Advertencias * ESM preload scripts must have the .mjs extension * Sandboxed preload scripts can't use ESM imports * Unsandboxed ESM preload scripts will run after page load on pages with no content * ESM preload scripts must be context isolated to use dynamic Node.js ESM imports Documentación * Empezar * Referencia de la API Listas de verificación * Rendimiento * Seguridad Herramientas * Electron Forge * Electron Fiddle Comunidad * Gobernanza * Recursos * Discord * Bluesky * X * Mastodon * Stack Overflow Más * GitHub * Open Collective * Infraestructura de Pizarra Hosting and infrastructure graciously provided by