About Electron

Electron is an open source library developed by GitHub for building cross-platform desktop applications with HTML, CSS, and JavaScript. Electron accomplishes this by combining Chromium and Node.js into a single runtime and apps can be packaged for Mac, Windows, and Linux.

Electron began in 2013 as the framework on which Atom, GitHub's hackable text editor, would be built. The two were open sourced in the Spring of 2014.

It has since become a popular tool used by open source developers, startups, and established companies. See who is building on Electron.

Read on to learn more about the contributors and releases of Electron or get started building with Electron in the Quick Start Guide.

Core Team and Contributors

Electron is maintained by a team at GitHub as well as a group of active contributors from the community. Some of the contributors are individuals and some work at larger companies who are developing on Electron. We're happy to add frequent contributors to the project as maintainers. Read more about contributing to Electron.

Releases

Electron releases frequently. We release when there are significant bug fixes, new APIs or are updating versions of Chromium or Node.js.

Updating Dependencies

Electron's version of Chromium is usually updated within one or two weeks after a new stable Chromium version is released, depending on the effort involved in the upgrade.

When a new version of Node.js is released, Electron usually waits about a month before upgrading in order to bring in a more stable version.

In Electron, Node.js and Chromium share a single V8 instance—usually the version that Chromium is using. Most of the time this just works but sometimes it means patching Node.js.

Versioning

As of version 2.0 Electron follows semver. For most applications, and using any recent version of npm, running $ npm install electron will do the right thing.

The version update process is detailed explicitly in our Versioning Doc.

LTS

Long term support of older versions of Electron does not currently exist. If your current version of Electron works for you, you can stay on it for as long as you'd like. If you want to make use of new features as they come in you should upgrade to a newer version.

A major update came with version v1.0.0. If you're not yet using this version, you should read more about the v1.0.0 changes.

Core Philosophy

In order to keep Electron small (file size) and sustainable (the spread of dependencies and APIs) the project limits the scope of the core project.

For instance, Electron uses Chromium's rendering library rather than all of Chromium. This makes it easier to upgrade Chromium but also means some browser features found in Google Chrome do not exist in Electron.

New features added to Electron should primarily be native APIs. If a feature can be its own Node.js module, it probably should be. See the Electron tools built by the community.

History

Below are milestones in Electron's history.

Accelerator

Define keyboard shortcuts.

Accelerators are Strings that can contain multiple modifiers and a single key code, combined by the + character, and are used to define keyboard shortcuts throughout your application.

Examples:

• CommandOrControl+A
• CommandOrControl+Shift+Z

Shortcuts are registered with the globalShortcut module using the register method, i.e.

const { app, globalShortcut } = require('electron')

app.on('ready', () => {
  // Register a 'CommandOrControl+Y' shortcut listener.
  globalShortcut.register('CommandOrControl+Y', () => {
    // Do stuff when Y and either Command/Control is pressed.
  })
})

Platform notice

On Linux and Windows, the Command key does not have any effect so use CommandOrControl which represents Command on macOS and Control on Linux and Windows to define some accelerators.

Use Alt instead of Option. The Option key only exists on macOS, whereas the Alt key is available on all platforms.

The Super key is mapped to the Windows key on Windows and Linux and Cmd on macOS.

Available modifiers

• Command (or Cmd for short)
• Control (or Ctrl for short)
• CommandOrControl (or CmdOrCtrl for short)
• Alt
• Option
• AltGr
• Shift
• Super

Available key codes

• 0 to 9
• A to Z
• F1 to F24
• Punctuations like ~, !, @, #, $, etc.
• Plus
• Space
• Tab
• Capslock
• Numlock
• Scrolllock
• Backspace
• Delete
• Insert
• Return (or Enter as alias)
• Up, Down, Left and Right
• Home and End
• PageUp and PageDown
• Escape (or Esc for short)
• VolumeUp, VolumeDown and VolumeMute
• MediaNextTrack, MediaPreviousTrack, MediaStop and MediaPlayPause
• PrintScreen

• NumPad Keys

  • num0 - num9
  • numdec - decimal key
  • numadd - numpad + key
  • numsub - numpad - key
  • nummult - numpad * key
  • numdiv - numpad ÷ key

Accessibility

Making accessible applications is important and we're happy to introduce new functionality to Devtron and Spectron that gives developers the opportunity to make their apps better for everyone.

Accessibility concerns in Electron applications are similar to those of websites because they're both ultimately HTML. With Electron apps, however, you can't use the online resources for accessibility audits because your app doesn't have a URL to point the auditor to.

These new features bring those auditing tools to your Electron app. You can choose to add audits to your tests with Spectron or use them within DevTools with Devtron. Read on for a summary of the tools.

Spectron

In the testing framework Spectron, you can now audit each window and <webview> tag in your application. For example:

app.client.auditAccessibility().then(function (audit) {
  if (audit.failed) {
    console.error(audit.message)
  }
})

You can read more about this feature in Spectron's documentation.

Devtron

In Devtron, there is a new accessibility tab which will allow you to audit a page in your app, sort and filter the results.

Both of these tools are using the Accessibility Developer Tools library built by Google for Chrome. You can learn more about the accessibility audit rules this library uses on that repository's wiki.

If you know of other great accessibility tools for Electron, add them to the accessibility documentation with a pull request.

Enabling Accessibility

Electron applications keep accessibility disabled by default for performance reasons but there are multiple ways to enable it.

Inside Application

By using app.setAccessibilitySupportEnabled(enabled), you can expose accessibility switch to users in the application preferences. User's system assistive utilities have priority over this setting and will override it.

Assistive Technology

Electron application will enable accessibility automatically when it detects assistive technology (Windows) or VoiceOver (macOS). See Chrome's accessibility documentation for more details.

On macOS, third-party assistive technology can switch accessibility inside Electron applications by setting the attribute AXManualAccessibility programmatically:

CFStringRef kAXManualAccessibility = CFSTR("AXManualAccessibility");

+ (void)enableAccessibility:(BOOL)enable inElectronApplication:(NSRunningApplication *)app
{
    AXUIElementRef appRef = AXUIElementCreateApplication(app.processIdentifier);
    if (appRef == nil)
        return;

    CFBooleanRef value = enable ? kCFBooleanTrue : kCFBooleanFalse;
    AXUIElementSetAttributeValue(appRef, kAXManualAccessibility, value);
    CFRelease(appRef);
}

app

Control your application's event lifecycle.

Process: Main

The following example shows how to quit the application when the last window is closed:

const { app } = require('electron')
app.on('window-all-closed', () => {
  app.quit()
})

Events

The app object emits the following events:

Event: 'will-finish-launching'

Emitted when the application has finished basic startup. On Windows and Linux, the will-finish-launching event is the same as the ready event; on macOS, this event represents the applicationWillFinishLaunching notification of NSApplication. You would usually set up listeners for the open-file and open-url events here, and start the crash reporter and auto updater.

In most cases, you should do everything in the ready event handler.

Event: 'ready'

Returns:

• launchInfo unknown macOS

Emitted when Electron has finished initializing. On macOS, launchInfo holds the userInfo of the NSUserNotification that was used to open the application, if it was launched from Notification Center. You can call app.isReady() to check if this event has already fired.

Event: 'window-all-closed'

Emitted when all windows have been closed.

If you do not subscribe to this event and all windows are closed, the default behavior is to quit the app; however, if you subscribe, you control whether the app quits or not. If the user pressed Cmd + Q, or the developer called app.quit(), Electron will first try to close all the windows and then emit the will-quit event, and in this case the window-all-closed event would not be emitted.

Event: 'before-quit'

Returns:

• event Event

Emitted before the application starts closing its windows. Calling event.preventDefault() will prevent the default behavior, which is terminating the application.

Note: If application quit was initiated by autoUpdater.quitAndInstall(), then before-quit is emitted after emitting close event on all windows and closing them.

Note: On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.

Event: 'will-quit'

Returns:

• event Event

Emitted when all windows have been closed and the application will quit. Calling event.preventDefault() will prevent the default behaviour, which is terminating the application.

See the description of the window-all-closed event for the differences between the will-quit and window-all-closed events.

Note: On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.

Event: 'quit'

Returns:

• event Event
• exitCode Integer

Emitted when the application is quitting.

Note: On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.

Event: 'open-file' macOS

Returns:

• event Event
• path String

Emitted when the user wants to open a file with the application. The open-file event is usually emitted when the application is already open and the OS wants to reuse the application to open the file. open-file is also emitted when a file is dropped onto the dock and the application is not yet running. Make sure to listen for the open-file event very early in your application startup to handle this case (even before the ready event is emitted).

You should call event.preventDefault() if you want to handle this event.

On Windows, you have to parse process.argv (in the main process) to get the filepath.

Event: 'open-url' macOS

Returns:

• event Event
• url String

Emitted when the user wants to open a URL with the application. Your application's Info.plist file must define the URL scheme within the CFBundleURLTypes key, and set NSPrincipalClass to AtomApplication.

You should call event.preventDefault() if you want to handle this event.

Event: 'activate' macOS

Returns:

• event Event
• hasVisibleWindows Boolean

Emitted when the application is activated. Various actions can trigger this event, such as launching the application for the first time, attempting to re-launch the application when it's already running, or clicking on the application's dock or taskbar icon.

Event: 'continue-activity' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.
• userInfo unknown - Contains app-specific state stored by the activity on another device.

Emitted during Handoff when an activity from a different device wants to be resumed. You should call event.preventDefault() if you want to handle this event.

A user activity can be continued only in an app that has the same developer Team ID as the activity's source app and that supports the activity's type. Supported activity types are specified in the app's Info.plist under the NSUserActivityTypes key.

Event: 'will-continue-activity' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.

Emitted during Handoff before an activity from a different device wants to be resumed. You should call event.preventDefault() if you want to handle this event.

Event: 'continue-activity-error' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.
• error String - A string with the error's localized description.

Emitted during Handoff when an activity from a different device fails to be resumed.

Event: 'activity-was-continued' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.
• userInfo unknown - Contains app-specific state stored by the activity.

Emitted during Handoff after an activity from this device was successfully resumed on another one.

Event: 'update-activity-state' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.
• userInfo unknown - Contains app-specific state stored by the activity.

Emitted when Handoff is about to be resumed on another device. If you need to update the state to be transferred, you should call event.preventDefault() immediately, construct a new userInfo dictionary and call app.updateCurrentActiviy() in a timely manner. Otherwise, the operation will fail and continue-activity-error will be called.

Event: 'new-window-for-tab' macOS

Returns:

• event Event

Emitted when the user clicks the native macOS new tab button. The new tab button is only visible if the current BrowserWindow has a tabbingIdentifier

Event: 'browser-window-blur'

Returns:

• event Event
• window BrowserWindow

Emitted when a browserWindow gets blurred.

Event: 'browser-window-focus'

Returns:

• event Event
• window BrowserWindow

Emitted when a browserWindow gets focused.

Event: 'browser-window-created'

Returns:

• event Event
• window BrowserWindow

Emitted when a new browserWindow is created.

Event: 'web-contents-created'

Returns:

• event Event
• webContents WebContents

Emitted when a new webContents is created.

Event: 'certificate-error'

Returns:

• event Event
• webContents WebContents
• url String
• error String - The error code
• certificate Certificate

• callback Function

  • isTrusted Boolean - Whether to consider the certificate as trusted

Emitted when failed to verify the certificate for url, to trust the certificate you should prevent the default behavior with event.preventDefault() and call callback(true).

const { app } = require('electron')

app.on('certificate-error', (event, webContents, url, error, certificate, callback) => {
  if (url === 'https://github.com') {
    // Verification logic.
    event.preventDefault()
    callback(true)
  } else {
    callback(false)
  }
})

Event: 'select-client-certificate'

Returns:

• event Event
• webContents WebContents
• url URL
• certificateList Certificate[]

• callback Function

  • certificate Certificate (optional)

Emitted when a client certificate is requested.

The url corresponds to the navigation entry requesting the client certificate and callback can be called with an entry filtered from the list. Using event.preventDefault() prevents the application from using the first certificate from the store.

const { app } = require('electron')

app.on('select-client-certificate', (event, webContents, url, list, callback) => {
  event.preventDefault()
  callback(list[0])
})

Event: 'login'

Returns:

• event Event
• webContents WebContents

• authenticationResponseDetails Object

  • url URL

• authInfo Object

  • isProxy Boolean
  • scheme String
  • host String
  • port Integer
  • realm String

• callback Function

  • username String (optional)
  • password String (optional)

Emitted when webContents wants to do basic auth.

The default behavior is to cancel all authentications. To override this you should prevent the default behavior with event.preventDefault() and call callback(username, password) with the credentials.

const { app } = require('electron')

app.on('login', (event, webContents, details, authInfo, callback) => {
  event.preventDefault()
  callback('username', 'secret')
})

If callback is called without a username or password, the authentication request will be cancelled and the authentication error will be returned to the page.

Event: 'gpu-info-update'

Emitted whenever there is a GPU info update.

Event: 'gpu-process-crashed'

Returns:

• event Event
• killed Boolean

Emitted when the GPU process crashes or is killed.

Event: 'renderer-process-crashed'

Returns:

• event Event
• webContents WebContents
• killed Boolean

Emitted when the renderer process of webContents crashes or is killed.

Event: 'accessibility-support-changed' macOS Windows

Returns:

• event Event
• accessibilitySupportEnabled Boolean - true when Chrome's accessibility support is enabled, false otherwise.

Emitted when Chrome's accessibility support changes. This event fires when assistive technologies, such as screen readers, are enabled or disabled. See https://www.chromium.org/developers/design-documents/accessibility for more details.

Event: 'session-created'

Returns:

• session Session

Emitted when Electron has created a new session.

const { app } = require('electron')

app.on('session-created', (event, session) => {
  console.log(session)
})

Event: 'second-instance'

Returns:

• event Event
• argv String[] - An array of the second instance's command line arguments
• workingDirectory String - The second instance's working directory

This event will be emitted inside the primary instance of your application when a second instance has been executed and calls app.requestSingleInstanceLock().

argv is an Array of the second instance's command line arguments, and workingDirectory is its current working directory. Usually applications respond to this by making their primary window focused and non-minimized.

This event is guaranteed to be emitted after the ready event of app gets emitted.

Note: Extra command line arguments might be added by Chromium, such as --original-process-start-time.

Event: 'desktop-capturer-get-sources'

Returns:

• event Event
• webContents WebContents

Emitted when desktopCapturer.getSources() is called in the renderer process of webContents. Calling event.preventDefault() will make it return empty sources.

Event: 'remote-require'

Returns:

• event Event
• webContents WebContents
• moduleName String

Emitted when remote.require() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the module from being returned. Custom value can be returned by setting event.returnValue.

Event: 'remote-get-global'

Returns:

• event Event
• webContents WebContents
• globalName String

Emitted when remote.getGlobal() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the global from being returned. Custom value can be returned by setting event.returnValue.

Event: 'remote-get-builtin'

Returns:

• event Event
• webContents WebContents
• moduleName String

Emitted when remote.getBuiltin() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the module from being returned. Custom value can be returned by setting event.returnValue.

Event: 'remote-get-current-window'

Returns:

• event Event
• webContents WebContents

Emitted when remote.getCurrentWindow() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the object from being returned. Custom value can be returned by setting event.returnValue.

Event: 'remote-get-current-web-contents'

Returns:

• event Event
• webContents WebContents

Emitted when remote.getCurrentWebContents() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the object from being returned. Custom value can be returned by setting event.returnValue.

Event: 'remote-get-guest-web-contents'

Returns:

• event Event
• webContents WebContents
• guestWebContents WebContents

Emitted when <webview>.getWebContents() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the object from being returned. Custom value can be returned by setting event.returnValue.

Methods

The app object has the following methods:

Note: Some methods are only available on specific operating systems and are labeled as such.

app.quit()

Try to close all windows. The before-quit event will be emitted first. If all windows are successfully closed, the will-quit event will be emitted and by default the application will terminate.

This method guarantees that all beforeunload and unload event handlers are correctly executed. It is possible that a window cancels the quitting by returning false in the beforeunload event handler.

app.exit([exitCode])

• exitCode Integer (optional)

Exits immediately with exitCode. exitCode defaults to 0.

All windows will be closed immediately without asking the user, and the before-quit and will-quit events will not be emitted.

app.relaunch([options])

• options Object (optional)

  • args String
  • execPath String (optional)

Relaunches the app when current instance exits.

By default, the new instance will use the same working directory and command line arguments with current instance. When args is specified, the args will be passed as command line arguments instead. When execPath is specified, the execPath will be executed for relaunch instead of current app.

Note that this method does not quit the app when executed, you have to call app.quit or app.exit after calling app.relaunch to make the app restart.

When app.relaunch is called for multiple times, multiple instances will be started after current instance exited.

An example of restarting current instance immediately and adding a new command line argument to the new instance:

const { app } = require('electron')

app.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })
app.exit(0)

app.isReady()

Returns Boolean - true if Electron has finished initializing, false otherwise.

app.whenReady()

Returns Promise<void> - fulfilled when Electron is initialized. May be used as a convenient alternative to checking app.isReady() and subscribing to the ready event if the app is not ready yet.

app.focus()

On Linux, focuses on the first visible window. On macOS, makes the application the active app. On Windows, focuses on the application's first window.

app.hide() macOS

Hides all application windows without minimizing them.

app.show() macOS

Shows application windows after they were hidden. Does not automatically focus them.

app.setAppLogsPath([path])

• path String (optional) - A custom path for your logs. Must be absolute.

Sets or creates a directory your app's logs which can then be manipulated with app.getPath() or app.setPath(pathName, newPath).

Calling app.setAppLogsPath() without a path parameter will result in this directory being set to ~/Library/Logs/YourAppName on macOS, and inside the userData directory on Linux and Windows.

app.getAppPath()

Returns String - The current application directory.

app.getPath(name)

• name String - You can request the following paths by the name:

  • home User's home directory.

  • appData Per-user application data directory, which by default points to:

    • %APPDATA% on Windows
    • $XDG_CONFIG_HOME or ~/.config on Linux
    • ~/Library/Application Support on macOS
  • userData The directory for storing your app's configuration files, which by default it is the appData directory appended with your app's name.
  • cache
  • temp Temporary directory.
  • exe The current executable file.
  • module The libchromiumcontent library.
  • desktop The current user's Desktop directory.
  • documents Directory for a user's "My Documents".
  • downloads Directory for a user's downloads.
  • music Directory for a user's music.
  • pictures Directory for a user's pictures.
  • videos Directory for a user's videos.
  • logs Directory for your app's log folder.
  • pepperFlashSystemPlugin Full path to the system version of the Pepper Flash plugin.

Returns String - A path to a special directory or file associated with name. On failure, an Error is thrown.

If app.getPath('logs') is called without called app.setAppLogsPath() being called first, a default log directory will be created equivalent to calling app.setAppLogsPath() without a path parameter.

app.getFileIcon(path[, options])

• path String

• options Object (optional)

  • size String

    • small - 16x16
    • normal - 32x32
    • large - 48x48 on Linux, 32x32 on Windows, unsupported on macOS.

Returns Promise<NativeImage> - fulfilled with the app's icon, which is a NativeImage.

Fetches a path's associated icon.

On Windows, there a 2 kinds of icons:

• Icons associated with certain file extensions, like .mp3, .png, etc.
• Icons inside the file itself, like .exe, .dll, .ico.

On Linux and macOS, icons depend on the application associated with file mime type.

app.setPath(name, path)

• name String
• path String

Overrides the path to a special directory or file associated with name. If the path specifies a directory that does not exist, an Error is thrown. In that case, the directory should be created with fs.mkdirSync or similar.

You can only override paths of a name defined in app.getPath.

By default, web pages' cookies and caches will be stored under the userData directory. If you want to change this location, you have to override the userData path before the ready event of the app module is emitted.

app.getVersion()

Returns String - The version of the loaded application. If no version is found in the application's package.json file, the version of the current bundle or executable is returned.

app.getName()

Returns String - The current application's name, which is the name in the application's package.json file.

Usually the name field of package.json is a short lowercase name, according to the npm modules spec. You should usually also specify a productName field, which is your application's full capitalized name, and which will be preferred over name by Electron.

Deprecated

app.setName(name)

• name String

Overrides the current application's name.

Deprecated

app.getLocale()

Returns String - The current application locale. Possible return values are documented here.

To set the locale, you'll want to use a command line switch at app startup, which may be found here.

Note: When distributing your packaged app, you have to also ship the locales folder.

Note: On Windows, you have to call it after the ready events gets emitted.

app.getLocaleCountryCode()

Returns String - User operating system's locale two-letter ISO 3166 country code. The value is taken from native OS APIs.

Note: When unable to detect locale country code, it returns empty string.

app.addRecentDocument(path) macOS Windows

• path String

Adds path to the recent documents list.

This list is managed by the OS. On Windows, you can visit the list from the task bar, and on macOS, you can visit it from dock menu.

app.clearRecentDocuments() macOS Windows

Clears the recent documents list.

app.setAsDefaultProtocolClient(protocol[, path, args])

• protocol String - The name of your protocol, without ://. If you want your app to handle electron:// links, call this method with electron as the parameter.
• path String (optional) Windows - Defaults to process.execPath
• args String Windows - Defaults to an empty array

Returns Boolean - Whether the call succeeded.

This method sets the current executable as the default handler for a protocol (aka URI scheme). It allows you to integrate your app deeper into the operating system. Once registered, all links with your-protocol:// will be opened with the current executable. The whole link, including protocol, will be passed to your application as a parameter.

On Windows, you can provide optional parameters path, the path to your executable, and args, an array of arguments to be passed to your executable when it launches.

Note: On macOS, you can only register protocols that have been added to your app's info.plist, which can not be modified at runtime. You can however change the file with a simple text editor or script during build time. Please refer to Apple's documentation for details.

Note: In a Windows Store environment (when packaged as an appx) this API will return true for all calls but the registry key it sets won't be accessible by other applications. In order to register your Windows Store application as a default protocol handler you must declare the protocol in your manifest.

The API uses the Windows Registry and LSSetDefaultHandlerForURLScheme internally.

app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windows

• protocol String - The name of your protocol, without ://.
• path String (optional) Windows - Defaults to process.execPath
• args String Windows - Defaults to an empty array

Returns Boolean - Whether the call succeeded.

This method checks if the current executable as the default handler for a protocol (aka URI scheme). If so, it will remove the app as the default handler.

app.isDefaultProtocolClient(protocol[, path, args])

• protocol String - The name of your protocol, without ://.
• path String (optional) Windows - Defaults to process.execPath
• args String Windows - Defaults to an empty array

Returns Boolean

This method checks if the current executable is the default handler for a protocol (aka URI scheme). If so, it will return true. Otherwise, it will return false.

Note: On macOS, you can use this method to check if the app has been registered as the default protocol handler for a protocol. You can also verify this by checking ~/Library/Preferences/com.apple.LaunchServices.plist on the macOS machine. Please refer to Apple's documentation for details.

The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internally.

app.setUserTasks(tasks) Windows

• tasks Task[] - Array of Task objects

Adds tasks to the Tasks category of the Jump List on Windows.

tasks is an array of Task objects.

Returns Boolean - Whether the call succeeded.

Note: If you'd like to customize the Jump List even more use app.setJumpList(categories) instead.

app.getJumpListSettings() Windows

Returns Object:

• minItems Integer - The minimum number of items that will be shown in the Jump List (for a more detailed description of this value see the MSDN docs).
• removedItems JumpListItem[] - Array of JumpListItem objects that correspond to items that the user has explicitly removed from custom categories in the Jump List. These items must not be re-added to the Jump List in the next call to app.setJumpList(), Windows will not display any custom category that contains any of the removed items.

app.setJumpList(categories) Windows

• categories JumpListCategory[] | null - Array of JumpListCategory objects.

Sets or removes a custom Jump List for the application, and returns one of the following strings:

• ok - Nothing went wrong.
• error - One or more errors occurred, enable runtime logging to figure out the likely cause.
• invalidSeparatorError - An attempt was made to add a separator to a custom category in the Jump List. Separators are only allowed in the standard Tasks category.
• fileTypeRegistrationError - An attempt was made to add a file link to the Jump List for a file type the app isn't registered to handle.
• customCategoryAccessDeniedError - Custom categories can't be added to the Jump List due to user privacy or group policy settings.

If categories is null the previously set custom Jump List (if any) will be replaced by the standard Jump List for the app (managed by Windows).

Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. If the name property is set but the type property is omitted then the type is assumed to be custom.

Note: Users can remove items from custom categories, and Windows will not allow a removed item to be added back into a custom category until after the next successful call to app.setJumpList(categories). Any attempt to re-add a removed item to a custom category earlier than that will result in the entire custom category being omitted from the Jump List. The list of removed items can be obtained using app.getJumpListSettings().

Here's a very simple example of creating a custom Jump List:

const { app } = require('electron')

app.setJumpList([
  {
    type: 'custom',
    name: 'Recent Projects',
    items: [
      { type: 'file', path: 'C:\\Projects\\project1.proj' },
      { type: 'file', path: 'C:\\Projects\\project2.proj' }
    ]
  },
  { // has a name so `type` is assumed to be "custom"
    name: 'Tools',
    items: [
      {
        type: 'task',
        title: 'Tool A',
        program: process.execPath,
        args: '--run-tool-a',
        icon: process.execPath,
        iconIndex: 0,
        description: 'Runs Tool A'
      },
      {
        type: 'task',
        title: 'Tool B',
        program: process.execPath,
        args: '--run-tool-b',
        icon: process.execPath,
        iconIndex: 0,
        description: 'Runs Tool B'
      }
    ]
  },
  { type: 'frequent' },
  { // has no name and no type so `type` is assumed to be "tasks"
    items: [
      {
        type: 'task',
        title: 'New Project',
        program: process.execPath,
        args: '--new-project',
        description: 'Create a new project.'
      },
      { type: 'separator' },
      {
        type: 'task',
        title: 'Recover Project',
        program: process.execPath,
        args: '--recover-project',
        description: 'Recover Project'
      }
    ]
  }
])

app.requestSingleInstanceLock()

Returns Boolean

The return value of this method indicates whether or not this instance of your application successfully obtained the lock. If it failed to obtain the lock, you can assume that another instance of your application is already running with the lock and exit immediately.

I.e. This method returns true if your process is the primary instance of your application and your app should continue loading. It returns false if your process should immediately quit as it has sent its parameters to another instance that has already acquired the lock.

On macOS, the system enforces single instance automatically when users try to open a second instance of your app in Finder, and the open-file and open-url events will be emitted for that. However when users start your app in command line, the system's single instance mechanism will be bypassed, and you have to use this method to ensure single instance.

An example of activating the window of primary instance when a second instance starts:

const { app } = require('electron')
let myWindow = null

const gotTheLock = app.requestSingleInstanceLock()

if (!gotTheLock) {
  app.quit()
} else {
  app.on('second-instance', (event, commandLine, workingDirectory) => {
    // Someone tried to run a second instance, we should focus our window.
    if (myWindow) {
      if (myWindow.isMinimized()) myWindow.restore()
      myWindow.focus()
    }
  })

  // Create myWindow, load the rest of the app, etc...
  app.on('ready', () => {
  })
}

app.hasSingleInstanceLock()

Returns Boolean

This method returns whether or not this instance of your app is currently holding the single instance lock. You can request the lock with app.requestSingleInstanceLock() and release with app.releaseSingleInstanceLock()

app.releaseSingleInstanceLock()

Releases all locks that were created by requestSingleInstanceLock. This will allow multiple instances of the application to once again run side by side.

app.setUserActivity(type, userInfo[, webpageURL]) macOS

• type String - Uniquely identifies the activity. Maps to NSUserActivity.activityType.
• userInfo any - App-specific state to store for use by another device.
• webpageURL String (optional) - The webpage to load in a browser if no suitable app is installed on the resuming device. The scheme must be http or https.

Creates an NSUserActivity and sets it as the current activity. The activity is eligible for Handoff to another device afterward.

app.getCurrentActivityType() macOS

Returns String - The type of the currently running activity.

app.invalidateCurrentActivity() macOS

Invalidates the current Handoff user activity.

app.resignCurrentActivity() macOS

Marks the current Handoff user activity as inactive without invalidating it.

app.updateCurrentActivity(type, userInfo) macOS

• type String - Uniquely identifies the activity. Maps to NSUserActivity.activityType.
• userInfo any - App-specific state to store for use by another device.

Updates the current activity if its type matches type, merging the entries from userInfo into its current userInfo dictionary.

app.setAppUserModelId(id) Windows

• id String

Changes the Application User Model ID to id.

app.importCertificate(options, callback) Linux

• options Object

  • certificate String - Path for the pkcs12 file.
  • password String - Passphrase for the certificate.

• callback Function

  • result Integer - Result of import.

Imports the certificate in pkcs12 format into the platform certificate store. callback is called with the result of import operation, a value of 0 indicates success while any other value indicates failure according to Chromium net_error_list.

app.disableHardwareAcceleration()

Disables hardware acceleration for current app.

This method can only be called before app is ready.

app.disableDomainBlockingFor3DAPIs()

By default, Chromium disables 3D APIs (e.g. WebGL) until restart on a per domain basis if the GPU processes crashes too frequently. This function disables that behaviour.

This method can only be called before app is ready.

app.getAppMetrics()

Returns ProcessMetric[]: Array of ProcessMetric objects that correspond to memory and CPU usage statistics of all the processes associated with the app.

app.getGPUFeatureStatus()

Returns GPUFeatureStatus - The Graphics Feature Status from chrome://gpu/.

Note: This information is only usable after the gpu-info-update event is emitted.

app.getGPUInfo(infoType)

• infoType String - Can be basic or complete.

Returns Promise<unknown>

For infoType equal to complete: Promise is fulfilled with Object containing all the GPU Information as in chromium's GPUInfo object. This includes the version and driver information that's shown on chrome://gpu page.

For infoType equal to basic: Promise is fulfilled with Object containing fewer attributes than when requested with complete. Here's an example of basic response:

{ auxAttributes:
   { amdSwitchable: true,
     canSupportThreadedTextureMailbox: false,
     directComposition: false,
     directRendering: true,
     glResetNotificationStrategy: 0,
     inProcessGpu: true,
     initializationTime: 0,
     jpegDecodeAcceleratorSupported: false,
     optimus: false,
     passthroughCmdDecoder: false,
     sandboxed: false,
     softwareRendering: false,
     supportsOverlays: false,
     videoDecodeAcceleratorFlags: 0 },
gpuDevice:
   [ { active: true, deviceId: 26657, vendorId: 4098 },
     { active: false, deviceId: 3366, vendorId: 32902 } ],
machineModelName: 'MacBookPro',
machineModelVersion: '11.5' }

Using basic should be preferred if only basic information like vendorId or driverId is needed.

app.setBadgeCount(count) Linux macOS

• count Integer

Returns Boolean - Whether the call succeeded.

Sets the counter badge for current app. Setting the count to 0 will hide the badge.

On macOS, it shows on the dock icon. On Linux, it only works for Unity launcher.

Note: Unity launcher requires the existence of a .desktop file to work, for more information please read Desktop Environment Integration.

Deprecated

app.getBadgeCount() Linux macOS

Returns Integer - The current value displayed in the counter badge.

Deprecated

app.isUnityRunning() Linux

Returns Boolean - Whether the current desktop environment is Unity launcher.

app.getLoginItemSettings([options]) macOS Windows

• options Object (optional)

  • path String (optional) Windows - The executable path to compare against. Defaults to process.execPath.
  • args String Windows - The command-line arguments to compare against. Defaults to an empty array.

If you provided path and args options to app.setLoginItemSettings, then you need to pass the same arguments here for openAtLogin to be set correctly.

Returns Object:

• openAtLogin Boolean - true if the app is set to open at login.
• openAsHidden Boolean macOS - true if the app is set to open as hidden at login. This setting is not available on MAS builds.
• wasOpenedAtLogin Boolean macOS - true if the app was opened at login automatically. This setting is not available on MAS builds.
• wasOpenedAsHidden Boolean macOS - true if the app was opened as a hidden login item. This indicates that the app should not open any windows at startup. This setting is not available on MAS builds.
• restoreState Boolean macOS - true if the app was opened as a login item that should restore the state from the previous session. This indicates that the app should restore the windows that were open the last time the app was closed. This setting is not available on MAS builds.

app.setLoginItemSettings(settings) macOS Windows

• settings Object

  • openAtLogin Boolean (optional) - true to open the app at login, false to remove the app as a login item. Defaults to false.
  • openAsHidden Boolean (optional) macOS - true to open the app as hidden. Defaults to false. The user can edit this setting from the System Preferences so app.getLoginItemSettings().wasOpenedAsHidden should be checked when the app is opened to know the current value. This setting is not available on MAS builds.
  • path String (optional) Windows - The executable to launch at login. Defaults to process.execPath.
  • args String Windows - The command-line arguments to pass to the executable. Defaults to an empty array. Take care to wrap paths in quotes.

Set the app's login item settings.

To work with Electron's autoUpdater on Windows, which uses Squirrel, you'll want to set the launch path to Update.exe, and pass arguments that specify your application name. For example:

const appFolder = path.dirname(process.execPath)
const updateExe = path.resolve(appFolder, '..', 'Update.exe')
const exeName = path.basename(process.execPath)

app.setLoginItemSettings({
  openAtLogin: true,
  path: updateExe,
  args: [
    '--processStart', `"${exeName}"`,
    '--process-start-args', `"--hidden"`
  ]
})

app.isAccessibilitySupportEnabled() macOS Windows

Returns Boolean - true if Chrome's accessibility support is enabled, false otherwise. This API will return true if the use of assistive technologies, such as screen readers, has been detected. See https://www.chromium.org/developers/design-documents/accessibility for more details.

Deprecated

app.setAccessibilitySupportEnabled(enabled) macOS Windows

• enabled Boolean - Enable or disable accessibility tree rendering

Manually enables Chrome's accessibility support, allowing to expose accessibility switch to users in application settings. See Chromium's accessibility docs for more details. Disabled by default.

This API must be called after the ready event is emitted.

Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.

Deprecated

app.showAboutPanel() macOS Linux

Show the app's about panel options. These options can be overridden with app.setAboutPanelOptions(options).

app.setAboutPanelOptions(options) macOS Linux

• options Object

  • applicationName String (optional) - The app's name.
  • applicationVersion String (optional) - The app's version.
  • copyright String (optional) - Copyright information.
  • version String (optional) macOS - The app's build version number.
  • credits String (optional) macOS - Credit information.
  • authors String Linux - List of app authors.
  • website String (optional) Linux - The app's website.
  • iconPath String (optional) Linux - Path to the app's icon. Will be shown as 64x64 pixels while retaining aspect ratio.

Set the about panel options. This will override the values defined in the app's .plist file on MacOS. See the Apple docs for more details. On Linux, values must be set in order to be shown; there are no defaults.

app.isEmojiPanelSupported()

Returns Boolean - whether or not the current OS version allows for native emoji pickers.

app.showEmojiPanel() macOS Windows

Show the platform's native emoji picker.

app.startAccessingSecurityScopedResource(bookmarkData) mas

• bookmarkData String - The base64 encoded security scoped bookmark data returned by the dialog.showOpenDialog or dialog.showSaveDialog methods.

Returns Function - This function must be called once you have finished accessing the security scoped file. If you do not remember to stop accessing the bookmark, kernel resources will be leaked and your app will lose its ability to reach outside the sandbox completely, until your app is restarted.

// Start accessing the file.
const stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)
// You can now access the file outside of the sandbox 🎉

// Remember to stop accessing the file once you've finished with it.
stopAccessingSecurityScopedResource()

Start accessing a security scoped resource. With this method Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See Apple's documentation for a description of how this system works.

app.enableSandbox() Experimental

Enables full sandbox mode on the app.

This method can only be called before app is ready.

app.isInApplicationsFolder() macOS

Returns Boolean - Whether the application is currently running from the systems Application folder. Use in combination with app.moveToApplicationsFolder()

app.moveToApplicationsFolder([options]) macOS

• options Object (optional)

  • conflictHandler Function (optional) - A handler for potential conflict in move failure.

    • conflictType String - The type of move conflict encountered by the handler; can be exists or existsAndRunning, where exists means that an app of the same name is present in the Applications directory and existsAndRunning means both that it exists and that it's presently running.

Returns Boolean - Whether the move was successful. Please note that if the move is successful, your application will quit and relaunch.

No confirmation dialog will be presented by default. If you wish to allow the user to confirm the operation, you may do so using the dialog API.

NOTE: This method throws errors if anything other than the user causes the move to fail. For instance if the user cancels the authorization dialog, this method returns false. If we fail to perform the copy, then this method will throw an error. The message in the error should be informative and tell you exactly what went wrong.

By default, if an app of the same name as the one being moved exists in the Applications directory and is not running, the existing app will be trashed and the active app moved into its place. If it is running, the pre-existing running app will assume focus and the the previously active app will quit itself. This behavior can be changed by providing the optional conflict handler, where the boolean returned by the handler determines whether or not the move conflict is resolved with default behavior. i.e. returning false will ensure no further action is taken, returning true will result in the default behavior and the method continuing.

For example:

app.moveToApplicationsFolder({
  conflictHandler: (conflictType) => {
    if (conflictType === 'exists') {
      return dialog.showMessageBoxSync({
        type: 'question',
        buttons: ['Halt Move', 'Continue Move'],
        defaultId: 0,
        message: 'An app of this name already exists'
      }) === 1
    }
  }
})

Would mean that if an app already exists in the user directory, if the user chooses to 'Continue Move' then the function would continue with its default behavior and the existing app will be trashed and the active app moved into its place.

Properties

app.accessibilitySupportEnabled macOS Windows

A Boolean property that's true if Chrome's accessibility support is enabled, false otherwise. This property will be true if the use of assistive technologies, such as screen readers, has been detected. Setting this property to true manually enables Chrome's accessibility support, allowing developers to expose accessibility switch to users in application settings.

See Chromium's accessibility docs for more details. Disabled by default.

This API must be called after the ready event is emitted.

Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.

app.applicationMenu

A Menu | null property that returns Menu if one has been set and null otherwise. Users can pass a Menu to set this property.

app.badgeCount Linux macOS

An Integer property that returns the badge count for current app. Setting the count to 0 will hide the badge.

On macOS, setting this with any nonzero integer shows on the dock icon. On Linux, this property only works for Unity launcher.

Note: Unity launcher requires the existence of a .desktop file to work, for more information please read Desktop Environment Integration.

app.commandLine Readonly

A CommandLine object that allows you to read and manipulate the command line arguments that Chromium uses.

app.dock macOS Readonly

A Dock object that allows you to perform actions on your app icon in the user's dock on macOS.

app.isPackaged Readonly

A Boolean property that returns true if the app is packaged, false otherwise. For many apps, this property can be used to distinguish development and production environments.

app.name

A String property that indicates the current application's name, which is the name in the application's package.json file.

Usually the name field of package.json is a short lowercase name, according to the npm modules spec. You should usually also specify a productName field, which is your application's full capitalized name, and which will be preferred over name by Electron.

app.userAgentFallback

A String which is the user agent string Electron will use as a global fallback.

This is the user agent that will be used when no user agent is set at the webContents or session level. It is useful for ensuring that your entire app has the same user agent. Set to a custom value as early as possible in your app's initialization to ensure that your overridden value is used.

app.allowRendererProcessReuse

A Boolean which when true disables the overrides that Electron has in place to ensure renderer processes are restarted on every navigation. The current default value for this property is false.

The intention is for these overrides to become disabled by default and then at some point in the future this property will be removed. This property impacts which native modules you can use in the renderer process. For more information on the direction Electron is going with renderer process restarts and usage of native modules in the renderer process please check out this Tracking Issue.

Electron App Feedback Program

Electron is working on building a streamlined release process and having faster releases. To help with that, we have the App Feedback Program for large-scale Electron apps to test our beta releases and report app-specific issues to the Electron team. We use this program to help us prioritize work and get applications upgraded to the next stable release as soon as possible. There are a few requirements we expect from participants, such as attending short, online weekly check-ins. Please visit the blog post for details and sign-up.

Electron Application Architecture

Before we can dive into Electron's APIs, we need to discuss the two process types available in Electron. They are fundamentally different and important to understand.

Main and Renderer Processes

In Electron, the process that runs package.json's main script is called the main process. The script that runs in the main process can display a GUI by creating web pages. An Electron app always has one main process, but never more.

Since Electron uses Chromium for displaying web pages, Chromium's multi-process architecture is also used. Each web page in Electron runs in its own process, which is called the renderer process.

In normal browsers, web pages usually run in a sandboxed environment and are not allowed access to native resources. Electron users, however, have the power to use Node.js APIs in web pages allowing lower level operating system interactions.

Differences Between Main Process and Renderer Process

The main process creates web pages by creating BrowserWindow instances. Each BrowserWindow instance runs the web page in its own renderer process. When a BrowserWindow instance is destroyed, the corresponding renderer process is also terminated.

The main process manages all web pages and their corresponding renderer processes. Each renderer process is isolated and only cares about the web page running in it.

In web pages, calling native GUI related APIs is not allowed because managing native GUI resources in web pages is very dangerous and it is easy to leak resources. If you want to perform GUI operations in a web page, the renderer process of the web page must communicate with the main process to request that the main process perform those operations.

Aside: Communication Between Processes

In Electron, we have several ways to communicate between the main process and renderer processes, such as ipcRenderer and ipcMain modules for sending messages, and the remote module for RPC style communication. There is also an FAQ entry on how to share data between web pages.

Using Electron APIs

Electron offers a number of APIs that support the development of a desktop application in both the main process and the renderer process. In both processes, you'd access Electron's APIs by requiring its included module:

const electron = require('electron')

All Electron APIs are assigned a process type. Many of them can only be used from the main process, some of them only from a renderer process, some from both. The documentation for each individual API will state which process it can be used from.

A window in Electron is for instance created using the BrowserWindow class. It is only available in the main process.

// This will work in the main process, but be `undefined` in a
// renderer process:
const { BrowserWindow } = require('electron')

const win = new BrowserWindow()

Since communication between the processes is possible, a renderer process can call upon the main process to perform tasks. Electron comes with a module called remote that exposes APIs usually only available on the main process. In order to create a BrowserWindow from a renderer process, we'd use the remote as a middle-man:

// This will work in a renderer process, but be `undefined` in the
// main process:
const { remote } = require('electron')
const { BrowserWindow } = remote

const win = new BrowserWindow()

Using Node.js APIs

Electron exposes full access to Node.js both in the main and the renderer process. This has two important implications:

1) All APIs available in Node.js are available in Electron. Calling the following code from an Electron app works:

const fs = require('fs')

const root = fs.readdirSync('/')

// This will print all files at the root-level of the disk,
// either '/' or 'C:\'.
console.log(root)

As you might already be able to guess, this has important security implications if you ever attempt to load remote content. You can find more information and guidance on loading remote content in our security documentation.

2) You can use Node.js modules in your application. Pick your favorite npm module. npm offers currently the world's biggest repository of open-source code – the ability to use well-maintained and tested code that used to be reserved for server applications is one of the key features of Electron.

As an example, to use the official AWS SDK in your application, you'd first install it as a dependency:

npm install --save aws-sdk

Then, in your Electron app, require and use the module as if you were building a Node.js application:

// A ready-to-use S3 Client
const S3 = require('aws-sdk/clients/s3')

There is one important caveat: Native Node.js modules (that is, modules that require compilation of native code before they can be used) will need to be compiled to be used with Electron.

The vast majority of Node.js modules are not native. Only 400 out of the ~650,000 modules are native. However, if you do need native modules, please consult this guide on how to recompile them for Electron.

Application Debugging

Whenever your Electron application is not behaving the way you wanted it to, an array of debugging tools might help you find coding errors, performance bottlenecks, or optimization opportunities.

Renderer Process

The most comprehensive tool to debug individual renderer processes is the Chromium Developer Toolset. It is available for all renderer processes, including instances of BrowserWindow, BrowserView, and WebView. You can open them programmatically by calling the openDevTools() API on the webContents of the instance:

const { BrowserWindow } = require('electron')

let win = new BrowserWindow()
win.webContents.openDevTools()

Google offers excellent documentation for their developer tools. We recommend that you make yourself familiar with them - they are usually one of the most powerful utilities in any Electron Developer's tool belt.

Main Process

Debugging the main process is a bit trickier, since you cannot open developer tools for them. The Chromium Developer Tools can be used to debug Electron's main process thanks to a closer collaboration between Google / Chrome and Node.js, but you might encounter oddities like require not being present in the console.

For more information, see the Debugging the Main Process documentation.

Application Distribution

To distribute your app with Electron, you need to package and rebrand it. The easiest way to do this is to use one of the following third party packaging tools:

• electron-forge
• electron-builder
• electron-packager

These tools will take care of all the steps you need to take to end up with a distributable Electron applications, such as packaging your application, rebranding the executable, setting the right icons and optionally creating installers.

Manual distribution

You can also choose to manually get your app ready for distribution. The steps needed to do this are outlined below.

To distribute your app with Electron, you need to download Electron's prebuilt binaries. Next, the folder containing your app should be named app and placed in Electron's resources directory as shown in the following examples. Note that the location of Electron's prebuilt binaries is indicated with electron/ in the examples below.

On macOS:

electron/Electron.app/Contents/Resources/app/
├── package.json
├── main.js
└── index.html

On Windows and Linux:

electron/resources/app
├── package.json
├── main.js
└── index.html

Then execute Electron.app (or electron on Linux, electron.exe on Windows), and Electron will start as your app. The electron directory will then be your distribution to deliver to final users.

Packaging Your App into a File

Apart from shipping your app by copying all of its source files, you can also package your app into an asar archive to avoid exposing your app's source code to users.

To use an asar archive to replace the app folder, you need to rename the archive to app.asar, and put it under Electron's resources directory like below, and Electron will then try to read the archive and start from it.

On macOS:

electron/Electron.app/Contents/Resources/
└── app.asar

On Windows and Linux:

electron/resources/
└── app.asar

More details can be found in Application packaging.

Rebranding with Downloaded Binaries

After bundling your app into Electron, you will want to rebrand Electron before distributing it to users.

Windows

You can rename electron.exe to any name you like, and edit its icon and other information with tools like rcedit.

macOS

You can rename Electron.app to any name you want, and you also have to rename the CFBundleDisplayName, CFBundleIdentifier and CFBundleName fields in the following files:

• Electron.app/Contents/Info.plist
• Electron.app/Contents/Frameworks/Electron Helper.app/Contents/Info.plist

You can also rename the helper app to avoid showing Electron Helper in the Activity Monitor, but make sure you have renamed the helper app's executable file's name.

The structure of a renamed app would be like:

MyApp.app/Contents
├── Info.plist
├── MacOS/
│   └── MyApp
└── Frameworks/
    └── MyApp Helper.app
        ├── Info.plist
        └── MacOS/
            └── MyApp Helper

Linux

You can rename the electron executable to any name you like.

Rebranding by Rebuilding Electron from Source

It is also possible to rebrand Electron by changing the product name and building it from source. To do this you need to set the build argument corresponding to the product name (electron_product_name = "YourProductName") in the args.gn file and rebuild.

Creating a Custom Electron Fork

Creating a custom fork of Electron is almost certainly not something you will need to do in order to build your app, even for "Production Level" applications. Using a tool such as electron-packager or electron-forge will allow you to "Rebrand" Electron without having to do these steps.

You need to fork Electron when you have custom C++ code that you have patched directly into Electron, that either cannot be upstreamed, or has been rejected from the official version. As maintainers of Electron, we very much would like to make your scenario work, so please try as hard as you can to get your changes into the official version of Electron, it will be much much easier on you, and we appreciate your help.

Creating a Custom Release with surf-build

1. Install Surf, via npm: npm install -g surf-build@latest

2. Create a new S3 bucket and create the following empty directory structure:

   - electron/
     - symbols/
     - dist/

3. Set the following Environment Variables:

• ELECTRON_GITHUB_TOKEN - a token that can create releases on GitHub
• ELECTRON_S3_ACCESS_KEY, ELECTRON_S3_BUCKET, ELECTRON_S3_SECRET_KEY - the place where you'll upload Node.js headers as well as symbols
• ELECTRON_RELEASE - Set to true and the upload part will run, leave unset and surf-build will do CI-type checks, appropriate to run for every pull request.
• CI - Set to true or else it will fail
• GITHUB_TOKEN - set it to the same as ELECTRON_GITHUB_TOKEN
• SURF_TEMP - set to C:\Temp on Windows to prevent path too long issues
• TARGET_ARCH - set to ia32 or x64

4. In script/upload.py, you must set ELECTRON_REPO to your fork (MYORG/electron), especially if you are a contributor to Electron proper.

5. surf-build -r https://github.com/MYORG/electron -s YOUR_COMMIT -n 'surf-PLATFORM-ARCH'

6. Wait a very, very long time for the build to complete.

Application Packaging

To mitigate issues around long path names on Windows, slightly speed up require and conceal your source code from cursory inspection, you can choose to package your app into an asar archive with little changes to your source code.

Most users will get this feature for free, since it's supported out of the box by electron-packager, electron-forge, and electron-builder. If you are not using any of these tools, read on.

Generating asar Archives

An asar archive is a simple tar-like format that concatenates files into a single file. Electron can read arbitrary files from it without unpacking the whole file.

Steps to package your app into an asar archive:

1. Install the asar Utility

$ npm install -g asar

2. Package with asar pack

$ asar pack your-app app.asar

Using asar Archives

In Electron there are two sets of APIs: Node APIs provided by Node.js and Web APIs provided by Chromium. Both APIs support reading files from asar archives.

Node API

With special patches in Electron, Node APIs like fs.readFile and require treat asar archives as virtual directories, and the files in it as normal files in the filesystem.

For example, suppose we have an example.asar archive under /path/to:

$ asar list /path/to/example.asar
/app.js
/file.txt
/dir/module.js
/static/index.html
/static/main.css
/static/jquery.min.js

Read a file in the asar archive:

const fs = require('fs')
fs.readFileSync('/path/to/example.asar/file.txt')

List all files under the root of the archive:

const fs = require('fs')
fs.readdirSync('/path/to/example.asar')

Use a module from the archive:

require('/path/to/example.asar/dir/module.js')

You can also display a web page in an asar archive with BrowserWindow:

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

win.loadURL('file:///path/to/example.asar/static/index.html')

Web API

In a web page, files in an archive can be requested with the file: protocol. Like the Node API, asar archives are treated as directories.

For example, to get a file with $.get:

<script>
let $ = require('./jquery.min.js')
$.get('file:///path/to/example.asar/file.txt', (data) => {
  console.log(data)
})
</script>

Treating an asar Archive as a Normal File

For some cases like verifying the asar archive's checksum, we need to read the content of an asar archive as a file. For this purpose you can use the built-in original-fs module which provides original fs APIs without asar support:

const originalFs = require('original-fs')
originalFs.readFileSync('/path/to/example.asar')

You can also set process.noAsar to true to disable the support for asar in the fs module:

const fs = require('fs')
process.noAsar = true
fs.readFileSync('/path/to/example.asar')

Limitations of the Node API

Even though we tried hard to make asar archives in the Node API work like directories as much as possible, there are still limitations due to the low-level nature of the Node API.

Archives Are Read-only

The archives can not be modified so all Node APIs that can modify files will not work with asar archives.

Working Directory Can Not Be Set to Directories in Archive

Though asar archives are treated as directories, there are no actual directories in the filesystem, so you can never set the working directory to directories in asar archives. Passing them as the cwd option of some APIs will also cause errors.

Extra Unpacking on Some APIs

Most fs APIs can read a file or get a file's information from asar archives without unpacking, but for some APIs that rely on passing the real file path to underlying system calls, Electron will extract the needed file into a temporary file and pass the path of the temporary file to the APIs to make them work. This adds a little overhead for those APIs.

APIs that requires extra unpacking are:

• child_process.execFile
• child_process.execFileSync
• fs.open
• fs.openSync
• process.dlopen - Used by require on native modules

Fake Stat Information of fs.stat

The Stats object returned by fs.stat and its friends on files in asar archives is generated by guessing, because those files do not exist on the filesystem. So you should not trust the Stats object except for getting file size and checking file type.

Executing Binaries Inside asar Archive

There are Node APIs that can execute binaries like child_process.exec, child_process.spawn and child_process.execFile, but only execFile is supported to execute binaries inside asar archive.

This is because exec and spawn accept command instead of file as input, and commands are executed under shell. There is no reliable way to determine whether a command uses a file in asar archive, and even if we do, we can not be sure whether we can replace the path in command without side effects.

Adding Unpacked Files to asar Archives

As stated above, some Node APIs will unpack the file to the filesystem when called. Apart from the performance issues, various anti-virus scanners might be triggered by this behavior.

As a workaround, you can leave various files unpacked using the --unpack option. In the following example, shared libraries of native Node.js modules will not be packed:

$ asar pack app app.asar --unpack *.node

After running the command, you will notice that a folder named app.asar.unpacked was created together with the app.asar file. It contains the unpacked files and should be shipped together with the app.asar archive.

Technical Differences Between Electron and NW.js (formerly node-webkit)

Note: Electron was previously named Atom Shell.

Like NW.js, Electron provides a platform to write desktop applications with JavaScript and HTML and has Node integration to grant access to the low level system from web pages.

But there are also fundamental differences between the two projects that make Electron a completely separate product from NW.js:

1. Entry of Application

In NW.js the main entry point of an application is a web page or a JS script. You specify a html or js file in the package.json and it is opened in a browser window as the application's main window (in case of an html entrypoint) or the script is executed.

In Electron, the entry point is a JavaScript script. Instead of providing a URL directly, you manually create a browser window and load an HTML file using the API. You also need to listen to window events to decide when to quit the application.

Electron works more like the Node.js runtime. Electron's APIs are lower level so you can use it for browser testing in place of PhantomJS.

2. Build System

In order to avoid the complexity of building all of Chromium, Electron uses libchromiumcontent to access Chromium's Content API. libchromiumcontent is a single shared library that includes the Chromium Content module and all of its dependencies. Users don't need a powerful machine to build Electron.

3. Node Integration

In NW.js, the Node integration in web pages requires patching Chromium to work, while in Electron we chose a different way to integrate the libuv loop with each platform's message loop to avoid hacking Chromium. See the node_bindings code for how that was done.

4. Multi-context

If you are an experienced NW.js user, you should be familiar with the concept of Node context and web context. These concepts were invented because of how NW.js was implemented.

By using the multi-context feature of Node, Electron doesn't introduce a new JavaScript context in web pages.

Note: NW.js has optionally supported multi-context since 0.13.

autoUpdater

Enable apps to automatically update themselves.

Process: Main

See also: A detailed guide about how to implement updates in your application.

autoUpdater is an EventEmitter.

Platform Notices

Currently, only macOS and Windows are supported. There is no built-in support for auto-updater on Linux, so it is recommended to use the distribution's package manager to update your app.

In addition, there are some subtle differences on each platform:

macOS

On macOS, the autoUpdater module is built upon Squirrel.Mac, meaning you don't need any special setup to make it work. For server-side requirements, you can read Server Support. Note that App Transport Security (ATS) applies to all requests made as part of the update process. Apps that need to disable ATS can add the NSAllowsArbitraryLoads key to their app's plist.

Note: Your application must be signed for automatic updates on macOS. This is a requirement of Squirrel.Mac.

Windows

On Windows, you have to install your app into a user's machine before you can use the autoUpdater, so it is recommended that you use the electron-winstaller, electron-forge or the grunt-electron-installer package to generate a Windows installer.

When using electron-winstaller or electron-forge make sure you do not try to update your app the first time it runs (Also see this issue for more info). It's also recommended to use electron-squirrel-startup to get desktop shortcuts for your app.

The installer generated with Squirrel will create a shortcut icon with an Application User Model ID in the format of com.squirrel.PACKAGE_ID.YOUR_EXE_WITHOUT_DOT_EXE, examples are com.squirrel.slack.Slack and com.squirrel.code.Code. You have to use the same ID for your app with app.setAppUserModelId API, otherwise Windows will not be able to pin your app properly in task bar.

Unlike Squirrel.Mac, Windows can host updates on S3 or any other static file host. You can read the documents of Squirrel.Windows to get more details about how Squirrel.Windows works.

Events

The autoUpdater object emits the following events:

Event: 'error'

Returns:

• error Error

Emitted when there is an error while updating.

Event: 'checking-for-update'

Emitted when checking if an update has started.

Event: 'update-available'

Emitted when there is an available update. The update is downloaded automatically.

Event: 'update-not-available'

Emitted when there is no available update.

Event: 'update-downloaded'

Returns:

• event Event
• releaseNotes String
• releaseName String
• releaseDate Date
• updateURL String

Emitted when an update has been downloaded.

On Windows only releaseName is available.

Note: It is not strictly necessary to handle this event. A successfully downloaded update will still be applied the next time the application starts.

Event: 'before-quit-for-update'

This event is emitted after a user calls quitAndInstall().

When this API is called, the before-quit event is not emitted before all windows are closed. As a result you should listen to this event if you wish to perform actions before the windows are closed while a process is quitting, as well as listening to before-quit.

Methods

The autoUpdater object has the following methods:

autoUpdater.setFeedURL(options)

• options Object

  • url String
  • headers Record<String, String> (optional) macOS - HTTP request headers.
  • serverType String (optional) macOS - Either json or default, see the Squirrel.Mac README for more information.

Sets the url and initialize the auto updater.

autoUpdater.getFeedURL()

Returns String - The current update feed URL.

autoUpdater.checkForUpdates()

Asks the server whether there is an update. You must call setFeedURL before using this API.

autoUpdater.quitAndInstall()

Restarts the app and installs the update after it has been downloaded. It should only be called after update-downloaded has been emitted.

Under the hood calling autoUpdater.quitAndInstall() will close all application windows first, and automatically call app.quit() after all windows have been closed.

Note: It is not strictly necessary to call this function to apply an update, as a successfully downloaded update will always be applied the next time the application starts.

Automated Testing with a Custom Driver

To write automated tests for your Electron app, you will need a way to "drive" your application. Spectron is a commonly-used solution which lets you emulate user actions via WebDriver. However, it's also possible to write your own custom driver using node's builtin IPC-over-STDIO. The benefit of a custom driver is that it tends to require less overhead than Spectron, and lets you expose custom methods to your test suite.

To create a custom driver, we'll use Node.js' child_process API. The test suite will spawn the Electron process, then establish a simple messaging protocol:

const childProcess = require('child_process')
const electronPath = require('electron')

// spawn the process
let env = { /* ... */ }
let stdio = ['inherit', 'inherit', 'inherit', 'ipc']
let appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })

// listen for IPC messages from the app
appProcess.on('message', (msg) => {
  // ...
})

// send an IPC message to the app
appProcess.send({ my: 'message' })

From within the Electron app, you can listen for messages and send replies using the Node.js process API:

// listen for IPC messages from the test suite
process.on('message', (msg) => {
  // ...
})

// send an IPC message to the test suite
process.send({ my: 'message' })

We can now communicate from the test suite to the Electron app using the appProcess object.

For convenience, you may want to wrap appProcess in a driver object that provides more high-level functions. Here is an example of how you can do this:

class TestDriver {
  constructor ({ path, args, env }) {
    this.rpcCalls = []

    // start child process
    env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages
    this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })

    // handle rpc responses
    this.process.on('message', (message) => {
      // pop the handler
      let rpcCall = this.rpcCalls[message.msgId]
      if (!rpcCall) return
      this.rpcCalls[message.msgId] = null
      // reject/resolve
      if (message.reject) rpcCall.reject(message.reject)
      else rpcCall.resolve(message.resolve)
    })

    // wait for ready
    this.isReady = this.rpc('isReady').catch((err) => {
      console.error('Application failed to start', err)
      this.stop()
      process.exit(1)
    })
  }

  // simple RPC call
  // to use: driver.rpc('method', 1, 2, 3).then(...)
  async rpc (cmd, ...args) {
    // send rpc request
    let msgId = this.rpcCalls.length
    this.process.send({ msgId, cmd, args })
    return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))
  }

  stop () {
    this.process.kill()
  }
}

In the app, you'd need to write a simple handler for the RPC calls:

if (process.env.APP_TEST_DRIVER) {
  process.on('message', onMessage)
}

async function onMessage ({ msgId, cmd, args }) {
  let method = METHODS[cmd]
  if (!method) method = () => new Error('Invalid method: ' + cmd)
  try {
    let resolve = await method(...args)
    process.send({ msgId, resolve })
  } catch (err) {
    let reject = {
      message: err.message,
      stack: err.stack,
      name: err.name
    }
    process.send({ msgId, reject })
  }
}

const METHODS = {
  isReady () {
    // do any setup needed
    return true
  }
  // define your RPC-able methods here
}

Then, in your test suite, you can use your test-driver as follows:

const test = require('ava')
const electronPath = require('electron')

let app = new TestDriver({
  path: electronPath,
  args: ['./app'],
  env: {
    NODE_ENV: 'test'
  }
})
test.before(async t => {
  await app.isReady
})
test.after.always('cleanup', async t => {
  await app.stop()
})

Updating an Appveyor Azure Image

Electron CI on Windows uses AppVeyor, which in turn uses Azure VM images to run. Occasionally, these VM images need to be updated due to changes in Chromium requirements. In order to update you will need PowerShell and the Azure PowerShell module.

Occasionally we need to update these images owing to changes in Chromium or other miscellaneous build requirement changes.

Example Use Case: * We need VS15.9 and we have VS15.7 installed; this would require us to update an Azure image.

1. Identify the image you wish to modify.

   • In appveyor.yml, the image is identified by the property image.

     • The names used correspond to the "images" defined for a build cloud, eg the libcc-20 cloud.

   • Find the image you wish to modify in the build cloud and make note of the VHD Blob Path for that image, which is the value for that corresponding key.

     • You will need this URI path to copy into a new image.
   • You will also need the storage account name which is labeled in AppVeyor as the Disk Storage Account Name

2. Get the Azure storage account key

   • Log into Azure using credentials stored in LastPass (under Azure Enterprise) and then find the storage account corresponding to the name found in AppVeyor.

     • Example, for appveyorlibccbuilds Disk Storage Account Name you'd look for appveyorlibccbuilds in the list of storage accounts @ Home < Storage Accounts

       • Click into it and look for Access Keys, and then you can use any of the keys present in the list.

3. Get the full virtual machine image URI from Azure

   • Navigate to Home < Storage Accounts < $ACCT_NAME < Blobs < Images

     • In the following list, look for the VHD path name you got from Appveyor and then click on it.

       • Copy the whole URL from the top of the subsequent window.

4. Copy the image using the Copy Master Image PowerShell script.

   • It is essential to copy the VM because if you spin up a VM against an image that image cannot at the same time be used by AppVeyor.

   • Use the storage account name, key, and URI obtained from Azure to run this script.

     • See Step 3 for URI & when prompted, press enter to use same storage account as destination.
     • Use default destination container name (images)

     • Also, when naming the copy, use a name that indicates what the new image will contain (if that has changed) and date stamp.

       • Ex. libcc-20core-vs2017-15.9-2019-04-15.vhd
   • Go into Azure and get the URI for the newly created image as described in a previous step

5. Spin up a new VM using the Create Master VM from VHD PowerShell.

   • From PowerShell, execute ps1 file with ./create_master_vm_from_vhd.ps1

   • You will need the credential information available in the AppVeyor build cloud definition.

     • This includes:

       • Client ID
       • Client Secret
       • Tenant ID
       • Subscription ID
       • Resource Group
       • Virtual Network

   • You will also need to specify

     • Master VM name - just a unique name to identify the temporary VM
     • Master VM size - use Standard_F32s_v2
     • Master VHD URI - use URI obtained @ end of previous step
     • Location use East US

6. Log back into Azure and find the VM you just created in Homee < Virtual Machines < $YOUR_NEW_VM

   • You can download a RDP (Remote Desktop) file to access the VM.

7. Using Microsoft Remote Desktop, click Connect to connect to the VM.

   • Credentials for logging into the VM are found in LastPass under the AppVeyor Enterprise master VM credentials.

8. Modify the VM as required.

9. Shut down the VM and then delete it in Azure.

10. Add the new image to the Appveyor Cloud settings or modify an existing image to point to the new VHD.

BluetoothDevice Object

• deviceName String
• deviceId String

Boilerplates and CLIs

Electron development is unopinionated - there is no "one true way" to develop, build, package, or release an Electron application. Additional features for Electron, both for build- and run-time, can usually be found on npm in individual packages, allowing developers to build both the app and build pipeline they need.

That level of modularity and extendability ensures that all developers working with Electron, both big and small in team-size, are never restricted in what they can or cannot do at any time during their development lifecycle. However, for many developers, one of the community-driven boilerplates or command line tools might make it dramatically easier to compile, package, and release an app.

Boilerplate vs CLI

A boilerplate is only a starting point - a canvas, so to speak - from which you build your application. They usually come in the form of a repository you can clone and customize to your heart's content.

A command line tool on the other hand continues to support you throughout the development and release. They are more helpful and supportive but enforce guidelines on how your code should be structured and built. Especially for beginners, using a command line tool is likely to be helpful.

electron-forge

A "complete tool for building modern Electron applications". Electron Forge unifies the existing (and well maintained) build tools for Electron development into a cohesive package so that anyone can jump right in to Electron development.

Forge comes with a ready-to-use template using Webpack as a bundler. It includes an example typescript configuration and provides two configuration files to enable easy customization. It uses the same core modules used by the greater Electron community (like electron-packager) –  changes made by Electron maintainers (like Slack) benefit Forge's users, too.

You can find more information and documentation on electronforge.io.

electron-builder

A "complete solution to package and build a ready-for-distribution Electron app" that focuses on an integrated experience. electron-builder adds one single dependency focused on simplicity and manages all further requirements internally.

electron-builder replaces features and modules used by the Electron maintainers (such as the auto-updater) with custom ones. They are generally tighter integrated but will have less in common with popular Electron apps like Atom, Visual Studio Code, or Slack.

You can find more information and documentation in the repository.

electron-react-boilerplate

If you don't want any tools but only a solid boilerplate to build from, CT Lin's electron-react-boilerplate might be worth a look. It's quite popular in the community and uses electron-builder internally.

Other Tools and Boilerplates

The "Awesome Electron" list contains more tools and boilerplates to choose from. If you find the length of the list intimidating, don't forget that adding tools as you go along is a valid approach, too.

Breaking Changes

Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least one major version before the change is made.

FIXME comments

The FIXME string is used in code comments to denote things that should be fixed for future releases. See https://github.com/electron/electron/search?q=fixme

Planned Breaking API Changes (7.0)

Node Headers URL

This is the URL specified as disturl in a .npmrc file or as the --dist-url command line flag when building native Node modules. Both will be supported for the foreseeable future but it is recommended that you switch.

Deprecated: https://atom.io/download/electron

Replace with: https://electronjs.org/headers

session.clearAuthCache(options)

The session.clearAuthCache API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.

// Deprecated
session.clearAuthCache({ type: 'password' })
// Replace with
session.clearAuthCache()

powerMonitor.querySystemIdleState

// Removed in Electron 7.0
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = getSystemIdleState(threshold)

powerMonitor.querySystemIdleTime

// Removed in Electron 7.0
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = getSystemIdleTime()

webFrame Isolated World APIs

// Removed in Elecron 7.0
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// Replace with
webFrame.setIsolatedWorldInfo(
  worldId,
  {
    securityOrigin: 'some_origin',
    name: 'human_readable_name',
    csp: 'content_security_policy'
  })

Removal of deprecated marked property on getBlinkMemoryInfo

This property was removed in Chromium 77, and as such is no longer available.

webkitdirectory attribute for <input type="file"/>

 The webkitdirectory property on HTML file inputs allows them to select folders. Previous versions of Electron had an incorrect implementation where the event.target.files of the input returned a FileList that returned one File corresponding to the selected folder.  As of Electron 7, that FileList is now list of all files contained within the folder, similarly to Chrome, Firefox, and Edge (link to MDN docs).  As an illustration, take a folder with this structure: console folder ├── file1 ├── file2 └── file3   In Electron <=6, this would return a FileList with a File object for: console path/to/folder   In Electron 7, this now returns a FileList with a File object for: console /path/to/folder/file3 /path/to/folder/file2 /path/to/folder/file1   Note that webkitdirectory no longer exposes the path to the selected folder. If you require the path to the selected folder rather than the folder contents, see the dialog.showOpenDialog API (link).

Planned Breaking API Changes (6.0)

win.setMenu(null)

// Deprecated
win.setMenu(null)
// Replace with
win.removeMenu()

contentTracing.getTraceBufferUsage()

// Deprecated
contentTracing.getTraceBufferUsage((percentage, value) => {
  // do something
})
// Replace with
contentTracing.getTraceBufferUsage().then(infoObject => {
  // infoObject has percentage and value fields
})

electron.screen in renderer process

// Deprecated
require('electron').screen
// Replace with
require('electron').remote.screen

require in sandboxed renderers

// Deprecated
require('child_process')
// Replace with
require('electron').remote.require('child_process')

// Deprecated
require('fs')
// Replace with
require('electron').remote.require('fs')

// Deprecated
require('os')
// Replace with
require('electron').remote.require('os')

// Deprecated
require('path')
// Replace with
require('electron').remote.require('path')

powerMonitor.querySystemIdleState

// Deprecated
powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API
const idleState = getSystemIdleState(threshold)

powerMonitor.querySystemIdleTime

// Deprecated
powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API
const idleTime = getSystemIdleTime()

app.enableMixedSandbox

// Deprecated
app.enableMixedSandbox()

Mixed-sandbox mode is now enabled by default.

Tray

Under macOS Catalina our former Tray implementation breaks. Apple's native substitute doesn't support changing the highlighting behavior.

// Deprecated
tray.setHighlightMode(mode)
// API will be removed in v7.0 without replacement.

Planned Breaking API Changes (5.0)

new BrowserWindow({ webPreferences })

The following webPreferences option default values are deprecated in favor of the new defaults listed below.

E.g. Re-enabling the webviewTag

const w = new BrowserWindow({
  webPreferences: {
    webviewTag: true
  }
})

nativeWindowOpen

Child windows opened with the nativeWindowOpen option will always have Node.js integration disabled, unless nodeIntegrationInSubFrames is `true.

Privileged Schemes Registration

Renderer process APIs webFrame.setRegisterURLSchemeAsPrivileged and webFrame.registerURLSchemeAsBypassingCSP as well as browser process API protocol.registerStandardSchemes have been removed. A new API, protocol.registerSchemesAsPrivileged has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready.

webFrame Isolated World APIs

// Removed in Electron 7.0
webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)
webFrame.setIsolatedWorldHumanReadableName(worldId, name)
webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)
// Replace with
webFrame.setIsolatedWorldInfo(
  worldId,
  {
    securityOrigin: 'some_origin',
    name: 'human_readable_name',
    csp: 'content_security_policy'
  })

webFrame.setSpellCheckProvider

The spellCheck callback is now asynchronous, and autoCorrectWord parameter has been removed.

// Deprecated
webFrame.setSpellCheckProvider('en-US', true, {
  spellCheck: (text) => {
    return !spellchecker.isMisspelled(text)
  }
})
// Replace with
webFrame.setSpellCheckProvider('en-US', {
  spellCheck: (words, callback) => {
    callback(words.filter(text => spellchecker.isMisspelled(text)))
  }
})

Planned Breaking API Changes (4.0)

The following list includes the breaking API changes made in Electron 4.0.

app.makeSingleInstance

// Deprecated
app.makeSingleInstance((argv, cwd) => {
  /* ... */
})
// Replace with
app.requestSingleInstanceLock()
app.on('second-instance', (event, argv, cwd) => {
  /* ... */
})

app.releaseSingleInstance

// Deprecated
app.releaseSingleInstance()
// Replace with
app.releaseSingleInstanceLock()

app.getGPUInfo

app.getGPUInfo('complete')
// Now behaves the same with `basic` on macOS
app.getGPUInfo('basic')

win_delay_load_hook

When building native modules for windows, the win_delay_load_hook variable in the module's binding.gyp must be true (which is the default). If this hook is not present, then the native module will fail to load on Windows, with an error message like Cannot find module. See the native module guide for more.

Breaking API Changes (3.0)

The following list includes the breaking API changes in Electron 3.0.

app

// Deprecated
app.getAppMemoryInfo()
// Replace with
app.getAppMetrics()

// Deprecated
const metrics = app.getAppMetrics()
const { memory } = metrics[0] // Deprecated property

BrowserWindow

// Deprecated
let optionsA = { webPreferences: { blinkFeatures: '' } }
let windowA = new BrowserWindow(optionsA)
// Replace with
let optionsB = { webPreferences: { enableBlinkFeatures: '' } }
let windowB = new BrowserWindow(optionsB)

// Deprecated
window.on('app-command', (e, cmd) => {
  if (cmd === 'media-play_pause') {
    // do something
  }
})
// Replace with
window.on('app-command', (e, cmd) => {
  if (cmd === 'media-play-pause') {
    // do something
  }
})

clipboard

// Deprecated
clipboard.readRtf()
// Replace with
clipboard.readRTF()

// Deprecated
clipboard.writeRtf()
// Replace with
clipboard.writeRTF()

// Deprecated
clipboard.readHtml()
// Replace with
clipboard.readHTML()

// Deprecated
clipboard.writeHtml()
// Replace with
clipboard.writeHTML()

crashReporter

// Deprecated
crashReporter.start({
  companyName: 'Crashly',
  submitURL: 'https://crash.server.com',
  autoSubmit: true
})
// Replace with
crashReporter.start({
  companyName: 'Crashly',
  submitURL: 'https://crash.server.com',
  uploadToServer: true
})

nativeImage

// Deprecated
nativeImage.createFromBuffer(buffer, 1.0)
// Replace with
nativeImage.createFromBuffer(buffer, {
  scaleFactor: 1.0
})

process

// Deprecated
const info = process.getProcessMemoryInfo()

screen

// Deprecated
screen.getMenuBarHeight()
// Replace with
screen.getPrimaryDisplay().workArea

session

// Deprecated
ses.setCertificateVerifyProc((hostname, certificate, callback) => {
  callback(true)
})
// Replace with
ses.setCertificateVerifyProc((request, callback) => {
  callback(0)
})

Tray

// Deprecated
tray.setHighlightMode(true)
// Replace with
tray.setHighlightMode('on')

// Deprecated
tray.setHighlightMode(false)
// Replace with
tray.setHighlightMode('off')

webContents

// Deprecated
webContents.openDevTools({ detach: true })
// Replace with
webContents.openDevTools({ mode: 'detach' })

// Removed
webContents.setSize(options)
// There is no replacement for this API

webFrame

// Deprecated
webFrame.registerURLSchemeAsSecure('app')
// Replace with
protocol.registerStandardSchemes(['app'], { secure: true })

// Deprecated
webFrame.registerURLSchemeAsPrivileged('app', { secure: true })
// Replace with
protocol.registerStandardSchemes(['app'], { secure: true })

<webview>

// Removed
webview.setAttribute('disableguestresize', '')
// There is no replacement for this API

// Removed
webview.setAttribute('guestinstance', instanceId)
// There is no replacement for this API

// Keyboard listeners no longer work on webview tag
webview.onkeydown = () => { /* handler */ }
webview.onkeyup = () => { /* handler */ }

Node Headers URL

This is the URL specified as disturl in a .npmrc file or as the --dist-url command line flag when building native Node modules.

Deprecated: https://atom.io/download/atom-shell

Replace with: https://atom.io/download/electron

Breaking API Changes (2.0)

The following list includes the breaking API changes made in Electron 2.0.

BrowserWindow

// Deprecated
let optionsA = { titleBarStyle: 'hidden-inset' }
let windowA = new BrowserWindow(optionsA)
// Replace with
let optionsB = { titleBarStyle: 'hiddenInset' }
let windowB = new BrowserWindow(optionsB)

menu

// Removed
menu.popup(browserWindow, 100, 200, 2)
// Replaced with
menu.popup(browserWindow, { x: 100, y: 200, positioningItem: 2 })

nativeImage

// Removed
nativeImage.toPng()
// Replaced with
nativeImage.toPNG()

// Removed
nativeImage.toJpeg()
// Replaced with
nativeImage.toJPEG()

process

• process.versions.electron and process.version.chrome will be made read-only properties for consistency with the other process.versions properties set by Node.

webContents

// Removed
webContents.setZoomLevelLimits(1, 2)
// Replaced with
webContents.setVisualZoomLevelLimits(1, 2)

webFrame

// Removed
webFrame.setZoomLevelLimits(1, 2)
// Replaced with
webFrame.setVisualZoomLevelLimits(1, 2)

<webview>

// Removed
webview.setZoomLevelLimits(1, 2)
// Replaced with
webview.setVisualZoomLevelLimits(1, 2)

Duplicate ARM Assets

Each Electron release includes two identical ARM builds with slightly different filenames, like electron-v1.7.3-linux-arm.zip and electron-v1.7.3-linux-armv7l.zip. The asset with the v7l prefix was added to clarify to users which ARM version it supports, and to disambiguate it from future armv6l and arm64 assets that may be produced.

The file without the prefix is still being published to avoid breaking any setups that may be consuming it. Starting at 2.0, the unprefixed file will no longer be published.

For details, see 6986 and 7189.

Breaking changes (NetworkService) (Draft)

This document describes changes to Electron APIs after migrating network code to NetworkService API.

We don't currently have an estimate of when we will enable NetworkService by default in Electron, but as Chromium is already removing non-NetworkService code, we might switch before Electron 10.

The content of this document should be moved to breaking-changes.md once we have determined when to enable NetworkService in Electron.

Planned Breaking API Changes

protocol.unregisterProtocol

protocol.uninterceptProtocol

The APIs are now synchronous and the optional callback is no longer needed.

// Deprecated
protocol.unregisterProtocol(scheme, () => { /* ... */ })
// Replace with
protocol.unregisterProtocol(scheme)

protocol.registerFileProtocol

protocol.registerBufferProtocol

protocol.registerStringProtocol

protocol.registerHttpProtocol

protocol.registerStreamProtocol

protocol.interceptFileProtocol

protocol.interceptStringProtocol

protocol.interceptBufferProtocol

protocol.interceptHttpProtocol

protocol.interceptStreamProtocol

The APIs are now synchronous and the optional callback is no longer needed.

// Deprecated
protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
// Replace with
protocol.registerFileProtocol(scheme, handler)

The registered or intercepted protocol does not have effect on current page until navigation happens.

protocol.isProtocolHandled

This API is deprecated and users should use protocol.isProtocolRegistered and protocol.isProtocolIntercepted instead.

// Deprecated
protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
// Replace with
const isRegistered = protocol.isProtocolRegistered(scheme)
const isIntercepted = protocol.isProtocolIntercepted(scheme)

Class: BrowserView

Create and control views.

Process: Main

A BrowserView can be used to embed additional web content into a BrowserWindow. It is like a child window, except that it is positioned relative to its owning window. It is meant to be an alternative to the webview tag.

Example

// In the main process.
const { BrowserView, BrowserWindow } = require('electron')

let win = new BrowserWindow({ width: 800, height: 600 })
win.on('closed', () => {
  win = null
})

let view = new BrowserView()
win.setBrowserView(view)
view.setBounds({ x: 0, y: 0, width: 300, height: 300 })
view.webContents.loadURL('https://electronjs.org')

new BrowserView([options]) Experimental

• options Object (optional)

  • webPreferences Object (optional) - See BrowserWindow.

Static Methods

BrowserView.getAllViews()

Returns BrowserView[] - An array of all opened BrowserViews.

BrowserView.fromWebContents(webContents)

• webContents WebContents

Returns BrowserView | null - The BrowserView that owns the given webContents or null if the contents are not owned by a BrowserView.

BrowserView.fromId(id)

• id Integer

Returns BrowserView - The view with the given id.

Instance Properties

Objects created with new BrowserView have the following properties:

view.webContents Experimental

A WebContents object owned by this view.

view.id Experimental

A Integer representing the unique ID of the view.

Instance Methods

Objects created with new BrowserView have the following instance methods:

view.destroy()

Force closing the view, the unload and beforeunload events won't be emitted for the web page. After you're done with a view, call this function in order to free memory and other resources as soon as possible.

view.isDestroyed()

Returns Boolean - Whether the view is destroyed.

view.setAutoResize(options) Experimental

• options Object

  • width Boolean (optional) - If true, the view's width will grow and shrink together with the window. false by default.
  • height Boolean (optional) - If true, the view's height will grow and shrink together with the window. false by default.
  • horizontal Boolean (optional) - If true, the view's x position and width will grow and shrink proportionally with the window. false by default.
  • vertical Boolean (optional) - If true, the view's y position and height will grow and shrink proportionally with the window. false by default.

view.setBounds(bounds) Experimental

• bounds Rectangle

Resizes and moves the view to the supplied bounds relative to the window.

view.getBounds() Experimental

Returns Rectangle

The bounds of this BrowserView instance as Object.

view.setBackgroundColor(color) Experimental

• color String - Color in #aarrggbb or #argb form. The alpha channel is optional.

BrowserWindow

Create and control browser windows.

Process: Main

// In the main process.
const { BrowserWindow } = require('electron')

// Or use `remote` from the renderer process.
// const { BrowserWindow } = require('electron').remote

let win = new BrowserWindow({ width: 800, height: 600 })
win.on('closed', () => {
  win = null
})

// Load a remote URL
win.loadURL('https://github.com')

// Or load a local HTML file
win.loadURL(`file://${__dirname}/app/index.html`)

Frameless window

To create a window without chrome, or a transparent window in arbitrary shape, you can use the Frameless Window API.

Showing window gracefully

When loading a page in the window directly, users may see the page load incrementally, which is not a good experience for a native app. To make the window display without visual flash, there are two solutions for different situations.

Using ready-to-show event

While loading the page, the ready-to-show event will be emitted when the renderer process has rendered the page for the first time if the window has not been shown yet. Showing the window after this event will have no visual flash:

const { BrowserWindow } = require('electron')
let win = new BrowserWindow({ show: false })
win.once('ready-to-show', () => {
  win.show()
})

This event is usually emitted after the did-finish-load event, but for pages with many remote resources, it may be emitted before the did-finish-load event.

Please note that using this event implies that the renderer will be considered "visible" and paint even though show is false. This event will never fire if you use paintWhenInitiallyHidden: false

Setting backgroundColor

For a complex app, the ready-to-show event could be emitted too late, making the app feel slow. In this case, it is recommended to show the window immediately, and use a backgroundColor close to your app's background:

const { BrowserWindow } = require('electron')

let win = new BrowserWindow({ backgroundColor: '#2e2c29' })
win.loadURL('https://github.com')

Note that even for apps that use ready-to-show event, it is still recommended to set backgroundColor to make app feel more native.

Parent and child windows

By using parent option, you can create child windows:

const { BrowserWindow } = require('electron')

let top = new BrowserWindow()
let child = new BrowserWindow({ parent: top })
child.show()
top.show()

The child window will always show on top of the top window.

Modal windows

A modal window is a child window that disables parent window, to create a modal window, you have to set both parent and modal options:

const { BrowserWindow } = require('electron')

let child = new BrowserWindow({ parent: top, modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
  child.show()
})

Page visibility

The Page Visibility API works as follows:

• On all platforms, the visibility state tracks whether the window is hidden/minimized or not.
• Additionally, on macOS, the visibility state also tracks the window occlusion state. If the window is occluded (i.e. fully covered) by another window, the visibility state will be hidden. On other platforms, the visibility state will be hidden only when the window is minimized or explicitly hidden with win.hide().
• If a BrowserWindow is created with show: false, the initial visibility state will be visible despite the window actually being hidden.
• If backgroundThrottling is disabled, the visibility state will remain visible even if the window is minimized, occluded, or hidden.

It is recommended that you pause expensive operations when the visibility state is hidden in order to minimize power consumption.

Platform notices

• On macOS modal windows will be displayed as sheets attached to the parent window.
• On macOS the child windows will keep the relative position to parent window when parent window moves, while on Windows and Linux child windows will not move.
• On Linux the type of modal windows will be changed to dialog.
• On Linux many desktop environments do not support hiding a modal window.

Class: BrowserWindow

Create and control browser windows.

Process: Main

BrowserWindow is an EventEmitter.

It creates a new BrowserWindow with native properties as set by the options.

new BrowserWindow([options])

• options Object (optional)

  • width Integer (optional) - Window's width in pixels. Default is 800.
  • height Integer (optional) - Window's height in pixels. Default is 600.
  • x Integer (optional) - (required if y is used) Window's left offset from screen. Default is to center the window.
  • y Integer (optional) - (required if x is used) Window's top offset from screen. Default is to center the window.
  • useContentSize Boolean (optional) - The width and height would be used as web page's size, which means the actual window's size will include window frame's size and be slightly larger. Default is false.
  • center Boolean (optional) - Show window in the center of the screen.
  • minWidth Integer (optional) - Window's minimum width. Default is 0.
  • minHeight Integer (optional) - Window's minimum height. Default is 0.
  • maxWidth Integer (optional) - Window's maximum width. Default is no limit.
  • maxHeight Integer (optional) - Window's maximum height. Default is no limit.
  • resizable Boolean (optional) - Whether window is resizable. Default is true.
  • movable Boolean (optional) - Whether window is movable. This is not implemented on Linux. Default is true.
  • minimizable Boolean (optional) - Whether window is minimizable. This is not implemented on Linux. Default is true.
  • maximizable Boolean (optional) - Whether window is maximizable. This is not implemented on Linux. Default is true.
  • closable Boolean (optional) - Whether window is closable. This is not implemented on Linux. Default is true.
  • focusable Boolean (optional) - Whether the window can be focused. Default is true. On Windows setting focusable: false also implies setting skipTaskbar: true. On Linux setting focusable: false makes the window stop interacting with wm, so the window will always stay on top in all workspaces.
  • alwaysOnTop Boolean (optional) - Whether the window should always stay on top of other windows. Default is false.
  • fullscreen Boolean (optional) - Whether the window should show in fullscreen. When explicitly set to false the fullscreen button will be hidden or disabled on macOS. Default is false.
  • fullscreenable Boolean (optional) - Whether the window can be put into fullscreen mode. On macOS, also whether the maximize/zoom button should toggle full screen mode or maximize window. Default is true.
  • simpleFullscreen Boolean (optional) - Use pre-Lion fullscreen on macOS. Default is false.
  • skipTaskbar Boolean (optional) - Whether to show the window in taskbar. Default is false.
  • kiosk Boolean (optional) - The kiosk mode. Default is false.
  • title String (optional) - Default window title. Default is "Electron". If the HTML tag <title> is defined in the HTML file loaded by loadURL(), this property will be ignored.
  • icon (NativeImage | String) (optional) - The window icon. On Windows it is recommended to use ICO icons to get best visual effects, you can also leave it undefined so the executable's icon will be used.
  • show Boolean (optional) - Whether window should be shown when created. Default is true.
  • paintWhenInitiallyHidden Boolean (optional) - Whether the renderer should be active when show is false and it has just been created. In order for document.visibilityState to work correctly on first load with show: false you should set this to false. Setting this to false will cause the ready-to-show event to not fire. Default is true.
  • frame Boolean (optional) - Specify false to create a Frameless Window. Default is true.
  • parent BrowserWindow (optional) - Specify parent window. Default is null.
  • modal Boolean (optional) - Whether this is a modal window. This only works when the window is a child window. Default is false.
  • acceptFirstMouse Boolean (optional) - Whether the web view accepts a single mouse-down event that simultaneously activates the window. Default is false.
  • disableAutoHideCursor Boolean (optional) - Whether to hide cursor when typing. Default is false.
  • autoHideMenuBar Boolean (optional) - Auto hide the menu bar unless the Alt key is pressed. Default is false.
  • enableLargerThanScreen Boolean (optional) - Enable the window to be resized larger than screen. Only relevant for macOS, as other OSes allow larger-than-screen windows by default. Default is false.
  • backgroundColor String (optional) - Window's background color as a hexadecimal value, like #66CD00 or #FFF or #80FFFFFF (alpha in #AARRGGBB format is supported if transparent is set to true). Default is #FFF (white).
  • hasShadow Boolean (optional) - Whether window should have a shadow. This is only implemented on macOS. Default is true.
  • opacity Number (optional) - Set the initial opacity of the window, between 0.0 (fully transparent) and 1.0 (fully opaque). This is only implemented on Windows and macOS.
  • darkTheme Boolean (optional) - Forces using dark theme for the window, only works on some GTK+3 desktop environments. Default is false.
  • transparent Boolean (optional) - Makes the window transparent. Default is false. On Windows, does not work unless the window is frameless.
  • type String (optional) - The type of window, default is normal window. See more about this below.

  • titleBarStyle String (optional) - The style of window title bar. Default is default. Possible values are:

    • default - Results in the standard gray opaque Mac title bar.
    • hidden - Results in a hidden title bar and a full size content window, yet the title bar still has the standard window controls ("traffic lights") in the top left.
    • hiddenInset - Results in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge.
    • customButtonsOnHover Boolean (optional) - Draw custom close, and minimize buttons on macOS frameless windows. These buttons will not display unless hovered over in the top left of the window. These custom buttons prevent issues with mouse events that occur with the standard window toolbar buttons. Note: This option is currently experimental.
  • fullscreenWindowTitle Boolean (optional) - Shows the title in the title bar in full screen mode on macOS for all titleBarStyle options. Default is false.
  • thickFrame Boolean (optional) - Use WS_THICKFRAME style for frameless windows on Windows, which adds standard window frame. Setting it to false will remove window shadow and window animations. Default is true.
  • vibrancy String (optional) - Add a type of vibrancy effect to the window, only on macOS. Can be appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, or under-page. Please note that using frame: false in combination with a vibrancy value requires that you use a non-default titleBarStyle as well. Also note that appearance-based, light, dark, medium-light, and ultra-dark have been deprecated and will be removed in an upcoming version of macOS.
  • zoomToPageWidth Boolean (optional) - Controls the behavior on macOS when option-clicking the green stoplight button on the toolbar or by clicking the Window > Zoom menu item. If true, the window will grow to the preferred width of the web page when zoomed, false will cause it to zoom to the width of the screen. This will also affect the behavior when calling maximize() directly. Default is false.
  • tabbingIdentifier String (optional) - Tab group name, allows opening the window as a native tab on macOS 10.12+. Windows with the same tabbing identifier will be grouped together. This also adds a native new tab button to your window's tab bar and allows your app and window to receive the new-window-for-tab event.

  • webPreferences Object (optional) - Settings of web page's features.

    • devTools Boolean (optional) - Whether to enable DevTools. If it is set to false, can not use BrowserWindow.webContents.openDevTools() to open DevTools. Default is true.
    • nodeIntegration Boolean (optional) - Whether node integration is enabled. Default is false.
    • nodeIntegrationInWorker Boolean (optional) - Whether node integration is enabled in web workers. Default is false. More about this can be found in Multithreading.
    • nodeIntegrationInSubFrames Boolean (optional) - Experimental option for enabling Node.js support in sub-frames such as iframes and child windows. All your preloads will load for every iframe, you can use process.isMainFrame to determine if you are in the main frame or not.
    • preload String (optional) - Specifies a script that will be loaded before other scripts run in the page. This script will always have access to node APIs no matter whether node integration is turned on or off. The value should be the absolute file path to the script. When node integration is turned off, the preload script can reintroduce Node global symbols back to the global scope. See example here.
    • sandbox Boolean (optional) - If set, this will sandbox the renderer associated with the window, making it compatible with the Chromium OS-level sandbox and disabling the Node.js engine. This is not the same as the nodeIntegration option and the APIs available to the preload script are more limited. Read more about the option here. Note: This option is currently experimental and may change or be removed in future Electron releases.
    • enableRemoteModule Boolean (optional) - Whether to enable the remote module. Default is true.
    • session Session (optional) - Sets the session used by the page. Instead of passing the Session object directly, you can also choose to use the partition option instead, which accepts a partition string. When both session and partition are provided, session will be preferred. Default is the default session.
    • partition String (optional) - Sets the session used by the page according to the session's partition string. If partition starts with persist:, the page will use a persistent session available to all pages in the app with the same partition. If there is no persist: prefix, the page will use an in-memory session. By assigning the same partition, multiple pages can share the same session. Default is the default session.
    • affinity String (optional) - When specified, web pages with the same affinity will run in the same renderer process. Note that due to reusing the renderer process, certain webPreferences options will also be shared between the web pages even when you specified different values for them, including but not limited to preload, sandbox and nodeIntegration. So it is suggested to use exact same webPreferences for web pages with the same affinity. This property is experimental
    • zoomFactor Number (optional) - The default zoom factor of the page, 3.0 represents 300%. Default is 1.0.
    • javascript Boolean (optional) - Enables JavaScript support. Default is true.
    • webSecurity Boolean (optional) - When false, it will disable the same-origin policy (usually using testing websites by people), and set allowRunningInsecureContent to true if this options has not been set by user. Default is true.
    • allowRunningInsecureContent Boolean (optional) - Allow an https page to run JavaScript, CSS or plugins from http URLs. Default is false.
    • images Boolean (optional) - Enables image support. Default is true.
    • textAreasAreResizable Boolean (optional) - Make TextArea elements resizable. Default is true.
    • webgl Boolean (optional) - Enables WebGL support. Default is true.
    • plugins Boolean (optional) - Whether plugins should be enabled. Default is false.
    • experimentalFeatures Boolean (optional) - Enables Chromium's experimental features. Default is false.
    • scrollBounce Boolean (optional) - Enables scroll bounce (rubber banding) effect on macOS. Default is false.
    • enableBlinkFeatures String (optional) - A list of feature strings separated by ,, like CSSVariables,KeyboardEventKey to enable. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.
    • disableBlinkFeatures String (optional) - A list of feature strings separated by ,, like CSSVariables,KeyboardEventKey to disable. The full list of supported feature strings can be found in the RuntimeEnabledFeatures.json5 file.

    • defaultFontFamily Object (optional) - Sets the default font for the font-family.

      • standard String (optional) - Defaults to Times New Roman.
      • serif String (optional) - Defaults to Times New Roman.
      • sansSerif String (optional) - Defaults to Arial.
      • monospace String (optional) - Defaults to Courier New.
      • cursive String (optional) - Defaults to Script.
      • fantasy String (optional) - Defaults to Impact.
    • defaultFontSize Integer (optional) - Defaults to 16.
    • defaultMonospaceFontSize Integer (optional) - Defaults to 13.
    • minimumFontSize Integer (optional) - Defaults to 0.
    • defaultEncoding String (optional) - Defaults to ISO-8859-1.
    • backgroundThrottling Boolean (optional) - Whether to throttle animations and timers when the page becomes background. This also affects the Page Visibility API. Defaults to true.
    • offscreen Boolean (optional) - Whether to enable offscreen rendering for the browser window. Defaults to false. See the offscreen rendering tutorial for more details.
    • contextIsolation Boolean (optional) - Whether to run Electron APIs and the specified preload script in a separate JavaScript context. Defaults to false. The context that the preload script runs in will still have full access to the document and window globals but it will use its own set of JavaScript builtins (Array, Object, JSON, etc.) and will be isolated from any changes made to the global environment by the loaded page. The Electron API will only be available in the preload script and not the loaded page. This option should be used when loading potentially untrusted remote content to ensure the loaded content cannot tamper with the preload script and any Electron APIs being used. This option uses the same technique used by Chrome Content Scripts. You can access this context in the dev tools by selecting the 'Electron Isolated Context' entry in the combo box at the top of the Console tab.
    • nativeWindowOpen Boolean (optional) - Whether to use native window.open(). Defaults to false. Child windows will always have node integration disabled unless nodeIntegrationInSubFrames is true. Note: This option is currently experimental.
    • webviewTag Boolean (optional) - Whether to enable the <webview> tag. Defaults to false. Note: The preload script configured for the <webview> will have node integration enabled when it is executed so you should ensure remote/untrusted content is not able to create a <webview> tag with a possibly malicious preload script. You can use the will-attach-webview event on webContents to strip away the preload script and to validate or alter the <webview>'s initial settings.
    • additionalArguments String - A list of strings that will be appended to process.argv in the renderer process of this app. Useful for passing small bits of data down to renderer process preload scripts.
    • safeDialogs Boolean (optional) - Whether to enable browser style consecutive dialog protection. Default is false.
    • safeDialogsMessage String (optional) - The message to display when consecutive dialog protection is triggered. If not defined the default message would be used, note that currently the default message is in English and not localized.
    • navigateOnDragDrop Boolean (optional) - Whether dragging and dropping a file or link onto the page causes a navigation. Default is false.
    • autoplayPolicy String (optional) - Autoplay policy to apply to content in the window, can be no-user-gesture-required, user-gesture-required, document-user-activation-required. Defaults to no-user-gesture-required.
    • disableHtmlFullscreenWindowResize Boolean (optional) - Whether to prevent the window from resizing when entering HTML Fullscreen. Default is false.

When setting minimum or maximum window size with minWidth/maxWidth/ minHeight/maxHeight, it only constrains the users. It won't prevent you from passing a size that does not follow size constraints to setBounds/setSize or to the constructor of BrowserWindow.

The possible values and behaviors of the type option are platform dependent. Possible values are:

• On Linux, possible types are desktop, dock, toolbar, splash, notification.

• On macOS, possible types are desktop, textured.

  • The textured type adds metal gradient appearance (NSTexturedBackgroundWindowMask).
  • The desktop type places the window at the desktop background window level (kCGDesktopWindowLevel - 1). Note that desktop window will not receive focus, keyboard or mouse events, but you can use globalShortcut to receive input sparingly.
• On Windows, possible type is toolbar.

Instance Events

Objects created with new BrowserWindow emit the following events:

Note: Some events are only available on specific operating systems and are labeled as such.

Event: 'page-title-updated'

Returns:

• event Event
• title String
• explicitSet Boolean

Emitted when the document changed its title, calling event.preventDefault() will prevent the native window's title from changing. explicitSet is false when title is synthesized from file URL.

Event: 'close'

Returns:

• event Event

Emitted when the window is going to be closed. It's emitted before the beforeunload and unload event of the DOM. Calling event.preventDefault() will cancel the close.

Usually you would want to use the beforeunload handler to decide whether the window should be closed, which will also be called when the window is reloaded. In Electron, returning any value other than undefined would cancel the close. For example:

window.onbeforeunload = (e) => {
  console.log('I do not want to be closed')

  // Unlike usual browsers that a message box will be prompted to users, returning
  // a non-void value will silently cancel the close.
  // It is recommended to use the dialog API to let the user confirm closing the
  // application.
  e.returnValue = false // equivalent to `return false` but not recommended
}

Note: There is a subtle difference between the behaviors of window.onbeforeunload = handler and window.addEventListener('beforeunload', handler). It is recommended to always set the event.returnValue explicitly, instead of only returning a value, as the former works more consistently within Electron.

Event: 'closed'

Emitted when the window is closed. After you have received this event you should remove the reference to the window and avoid using it any more.

Event: 'session-end' Windows

Emitted when window session is going to end due to force shutdown or machine restart or session log off.

Event: 'unresponsive'

Emitted when the web page becomes unresponsive.

Event: 'responsive'

Emitted when the unresponsive web page becomes responsive again.

Event: 'blur'

Emitted when the window loses focus.

Event: 'focus'

Emitted when the window gains focus.

Event: 'show'

Emitted when the window is shown.

Event: 'hide'

Emitted when the window is hidden.

Event: 'ready-to-show'

Emitted when the web page has been rendered (while not being shown) and window can be displayed without a visual flash.

Please note that using this event implies that the renderer will be considered "visible" and paint even though show is false. This event will never fire if you use paintWhenInitiallyHidden: false

Event: 'maximize'

Emitted when window is maximized.

Event: 'unmaximize'

Emitted when the window exits from a maximized state.

Event: 'minimize'

Emitted when the window is minimized.

Event: 'restore'

Emitted when the window is restored from a minimized state.

Event: 'will-resize' macOS Windows

Returns:

• event Event
• newBounds Rectangle - Size the window is being resized to.

Emitted before the window is resized. Calling event.preventDefault() will prevent the window from being resized.

Note that this is only emitted when the window is being resized manually. Resizing the window with setBounds/setSize will not emit this event.

Event: 'resize'

Emitted after the window has been resized.

Event: 'will-move' Windows

Returns:

• event Event
• newBounds Rectangle - Location the window is being moved to.

Emitted before the window is moved. Calling event.preventDefault() will prevent the window from being moved.

Note that this is only emitted when the window is being resized manually. Resizing the window with setBounds/setSize will not emit this event.

Event: 'move'

Emitted when the window is being moved to a new position.

Note: On macOS this event is an alias of moved.

Event: 'moved' macOS

Emitted once when the window is moved to a new position.

Event: 'enter-full-screen'

Emitted when the window enters a full-screen state.

Event: 'leave-full-screen'

Emitted when the window leaves a full-screen state.

Event: 'enter-html-full-screen'

Emitted when the window enters a full-screen state triggered by HTML API.

Event: 'leave-html-full-screen'

Emitted when the window leaves a full-screen state triggered by HTML API.

Event: 'always-on-top-changed'

Returns:

• event Event
• isAlwaysOnTop Boolean

Emitted when the window is set or unset to show always on top of other windows.

Event: 'app-command' Windows Linux

Returns:

• event Event
• command String

Emitted when an App Command is invoked. These are typically related to keyboard media keys or browser commands, as well as the "Back" button built into some mice on Windows.

Commands are lowercased, underscores are replaced with hyphens, and the APPCOMMAND_ prefix is stripped off. e.g. APPCOMMAND_BROWSER_BACKWARD is emitted as browser-backward.

const { BrowserWindow } = require('electron')
let win = new BrowserWindow()
win.on('app-command', (e, cmd) => {
  // Navigate the window back when the user hits their mouse back button
  if (cmd === 'browser-backward' && win.webContents.canGoBack()) {
    win.webContents.goBack()
  }
})

The following app commands are explicitly supported on Linux:

• browser-backward
• browser-forward

Event: 'scroll-touch-begin' macOS

Emitted when scroll wheel event phase has begun.

Event: 'scroll-touch-end' macOS

Emitted when scroll wheel event phase has ended.

Event: 'scroll-touch-edge' macOS

Emitted when scroll wheel event phase filed upon reaching the edge of element.

Event: 'swipe' macOS

Returns:

• event Event
• direction String

Emitted on 3-finger swipe. Possible directions are up, right, down, left.

Event: 'rotate-gesture' macOS

Returns:

• event Event
• rotation Float

Emitted on trackpad rotation gesture. Continually emitted until rotation gesture is ended. The rotation value on each emission is the angle in degrees rotated since the last emission. The last emitted event upon a rotation gesture will always be of value 0. Counter-clockwise rotation values are positive, while clockwise ones are negative.

Event: 'sheet-begin' macOS

Emitted when the window opens a sheet.

Event: 'sheet-end' macOS

Emitted when the window has closed a sheet.

Event: 'new-window-for-tab' macOS

Emitted when the native new tab button is clicked.

Static Methods

The BrowserWindow class has the following static methods:

BrowserWindow.getAllWindows()

Returns BrowserWindow[] - An array of all opened browser windows.

BrowserWindow.getFocusedWindow()

Returns BrowserWindow | null - The window that is focused in this application, otherwise returns null.

BrowserWindow.fromWebContents(webContents)

• webContents WebContents

Returns BrowserWindow - The window that owns the given webContents.

BrowserWindow.fromBrowserView(browserView)

• browserView BrowserView

Returns BrowserWindow | null - The window that owns the given browserView. If the given view is not attached to any window, returns null.

BrowserWindow.fromId(id)

• id Integer

Returns BrowserWindow - The window with the given id.

BrowserWindow.addExtension(path)

• path String

Adds Chrome extension located at path, and returns extension's name.

The method will also not return if the extension's manifest is missing or incomplete.

Note: This API cannot be called before the ready event of the app module is emitted.

BrowserWindow.removeExtension(name)

• name String

Remove a Chrome extension by name.

Note: This API cannot be called before the ready event of the app module is emitted.

BrowserWindow.getExtensions()

Returns Record<String, ExtensionInfo> - The keys are the extension names and each value is an Object containing name and version properties.

Note: This API cannot be called before the ready event of the app module is emitted.

BrowserWindow.addDevToolsExtension(path)

• path String

Adds DevTools extension located at path, and returns extension's name.

The extension will be remembered so you only need to call this API once, this API is not for programming use. If you try to add an extension that has already been loaded, this method will not return and instead log a warning to the console.

The method will also not return if the extension's manifest is missing or incomplete.

Note: This API cannot be called before the ready event of the app module is emitted.

BrowserWindow.removeDevToolsExtension(name)

• name String

Remove a DevTools extension by name.

Note: This API cannot be called before the ready event of the app module is emitted.

BrowserWindow.getDevToolsExtensions()

Returns Record<string, ExtensionInfo> - The keys are the extension names and each value is an Object containing name and version properties.

To check if a DevTools extension is installed you can run the following:

const { BrowserWindow } = require('electron')

let installed = BrowserWindow.getDevToolsExtensions().hasOwnProperty('devtron')
console.log(installed)

Note: This API cannot be called before the ready event of the app module is emitted.

Instance Properties

Objects created with new BrowserWindow have the following properties:

const { BrowserWindow } = require('electron')
// In this example `win` is our instance
let win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')

win.webContents Readonly

A WebContents object this window owns. All web page related events and operations will be done via it.

See the webContents documentation for its methods and events.

win.id Readonly

A Integer property representing the unique ID of the window.

win.autoHideMenuBar

A Boolean property that determines whether the window menu bar should hide itself automatically. Once set, the menu bar will only show when users press the single Alt key.

If the menu bar is already visible, setting this property to true won't hide it immediately.

win.minimizable

A Boolean property that determines whether the window can be manually minimized by user.

On Linux the setter is a no-op, although the getter returns true.

win.maximizable

A Boolean property that determines whether the window can be manually maximized by user.

On Linux the setter is a no-op, although the getter returns true.

win.fullScreenable

A Boolean property that determines whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.

win.resizable

A Boolean property that determines whether the window can be manually resized by user.

win.closable

A Boolean property that determines whether the window can be manually closed by user.

On Linux the setter is a no-op, although the getter returns true.

win.movable

A Boolean property that determines Whether the window can be moved by user.

On Linux the setter is a no-op, although the getter returns true.

win.excludedFromShownWindowsMenu macOS

A Boolean property that determines whether the window is excluded from the application’s Windows menu. false by default.

const win = new BrowserWindow({ height: 600, width: 600 })

const template = [
  {
    role: 'windowmenu'
  }
]

win.excludedFromShownWindowsMenu = true

const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)

Instance Methods

Objects created with new BrowserWindow have the following instance methods:

Note: Some methods are only available on specific operating systems and are labeled as such.

win.destroy()

Force closing the window, the unload and beforeunload event won't be emitted for the web page, and close event will also not be emitted for this window, but it guarantees the closed event will be emitted.

win.close()

Try to close the window. This has the same effect as a user manually clicking the close button of the window. The web page may cancel the close though. See the close event.

win.focus()

Focuses on the window.

win.blur()

Removes focus from the window.

win.isFocused()

Returns Boolean - Whether the window is focused.

win.isDestroyed()

Returns Boolean - Whether the window is destroyed.

win.show()

Shows and gives focus to the window.

win.showInactive()

Shows the window but doesn't focus on it.

win.hide()

Hides the window.

win.isVisible()

Returns Boolean - Whether the window is visible to the user.

win.isModal()

Returns Boolean - Whether current window is a modal window.

win.maximize()

Maximizes the window. This will also show (but not focus) the window if it isn't being displayed already.

win.unmaximize()

Unmaximizes the window.

win.isMaximized()

Returns Boolean - Whether the window is maximized.

win.minimize()

Minimizes the window. On some platforms the minimized window will be shown in the Dock.

win.restore()

Restores the window from minimized state to its previous state.

win.isMinimized()

Returns Boolean - Whether the window is minimized.

win.setFullScreen(flag)

• flag Boolean

Sets whether the window should be in fullscreen mode.

win.isFullScreen()

Returns Boolean - Whether the window is in fullscreen mode.

win.setSimpleFullScreen(flag) macOS

• flag Boolean

Enters or leaves simple fullscreen mode.

Simple fullscreen mode emulates the native fullscreen behavior found in versions of Mac OS X prior to Lion (10.7).

win.isSimpleFullScreen() macOS

Returns Boolean - Whether the window is in simple (pre-Lion) fullscreen mode.

win.isNormal()

Returns Boolean - Whether the window is in normal state (not maximized, not minimized, not in fullscreen mode).

win.setAspectRatio(aspectRatio[, extraSize]) macOS

• aspectRatio Float - The aspect ratio to maintain for some portion of the content view.
• extraSize Size (optional) - The extra size not to be included while maintaining the aspect ratio.

This will make a window maintain an aspect ratio. The extra size allows a developer to have space, specified in pixels, not included within the aspect ratio calculations. This API already takes into account the difference between a window's size and its content size.

Consider a normal window with an HD video player and associated controls. Perhaps there are 15 pixels of controls on the left edge, 25 pixels of controls on the right edge and 50 pixels of controls below the player. In order to maintain a 16:9 aspect ratio (standard aspect ratio for HD @1920x1080) within the player itself we would call this function with arguments of 16/9 and [ 40, 50 ]. The second argument doesn't care where the extra width and height are within the content view--only that they exist. Sum any extra width and height areas you have within the overall content view.

Calling this function with a value of 0 will remove any previously set aspect ratios.

win.setBackgroundColor(backgroundColor)

• backgroundColor String - Window's background color as a hexadecimal value, like #66CD00 or #FFF or #80FFFFFF (alpha is supported if transparent is true). Default is #FFF (white).

Sets the background color of the window. See Setting backgroundColor.

win.previewFile(path[, displayName]) macOS

• path String - The absolute path to the file to preview with QuickLook. This is important as Quick Look uses the file name and file extension on the path to determine the content type of the file to open.
• displayName String (optional) - The name of the file to display on the Quick Look modal view. This is purely visual and does not affect the content type of the file. Defaults to path.

Uses Quick Look to preview a file at a given path.

win.closeFilePreview() macOS

Closes the currently open Quick Look panel.

win.setBounds(bounds[, animate])

• bounds Partial<Rectangle>
• animate Boolean (optional) macOS

Resizes and moves the window to the supplied bounds. Any properties that are not supplied will default to their current values.

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

// set all bounds properties
win.setBounds({ x: 440, y: 225, width: 800, height: 600 })

// set a single bounds property
win.setBounds({ width: 100 })

// { x: 440, y: 225, width: 100, height: 600 }
console.log(win.getBounds())

win.getBounds()

Returns Rectangle - The bounds of the window as Object.

win.setContentBounds(bounds[, animate])

• bounds Rectangle
• animate Boolean (optional) macOS

Resizes and moves the window's client area (e.g. the web page) to the supplied bounds.

win.getContentBounds()

Returns Rectangle - The bounds of the window's client area as Object.

win.getNormalBounds()

Returns Rectangle - Contains the window bounds of the normal state

Note: whatever the current state of the window : maximized, minimized or in fullscreen, this function always returns the position and size of the window in normal state. In normal state, getBounds and getNormalBounds returns the same Rectangle.

win.setEnabled(enable)

• enable Boolean

Disable or enable the window.

win.isEnabled()

Returns Boolean - whether the window is enabled.

win.setSize(width, height[, animate])

• width Integer
• height Integer
• animate Boolean (optional) macOS

Resizes the window to width and height. If width or height are below any set minimum size constraints the window will snap to its minimum size.

win.getSize()

Returns Integer[] - Contains the window's width and height.

win.setContentSize(width, height[, animate])

• width Integer
• height Integer
• animate Boolean (optional) macOS

Resizes the window's client area (e.g. the web page) to width and height.

win.getContentSize()

Returns Integer[] - Contains the window's client area's width and height.

win.setMinimumSize(width, height)

• width Integer
• height Integer

Sets the minimum size of window to width and height.

win.getMinimumSize()

Returns Integer[] - Contains the window's minimum width and height.

win.setMaximumSize(width, height)

• width Integer
• height Integer

Sets the maximum size of window to width and height.

win.getMaximumSize()

Returns Integer[] - Contains the window's maximum width and height.

win.setResizable(resizable)

• resizable Boolean

Sets whether the window can be manually resized by user.

Deprecated

win.isResizable()

Returns Boolean - Whether the window can be manually resized by user.

Deprecated

win.setMovable(movable) macOS Windows

• movable Boolean

Sets whether the window can be moved by user. On Linux does nothing.

Deprecated

win.isMovable() macOS Windows

Returns Boolean - Whether the window can be moved by user.

On Linux always returns true.

Deprecated

win.setMinimizable(minimizable) macOS Windows

• minimizable Boolean

Sets whether the window can be manually minimized by user. On Linux does nothing.

Deprecated

win.isMinimizable() macOS Windows

Returns Boolean - Whether the window can be manually minimized by user

On Linux always returns true.

Deprecated

win.setMaximizable(maximizable) macOS Windows

• maximizable Boolean

Sets whether the window can be manually maximized by user. On Linux does nothing.

Deprecated

win.isMaximizable() macOS Windows

Returns Boolean - Whether the window can be manually maximized by user.

On Linux always returns true.

Deprecated

win.setFullScreenable(fullscreenable)

• fullscreenable Boolean

Sets whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.

Deprecated

win.isFullScreenable()

Returns Boolean - Whether the maximize/zoom window button toggles fullscreen mode or maximizes the window.

Deprecated

win.setClosable(closable) macOS Windows

• closable Boolean

Sets whether the window can be manually closed by user. On Linux does nothing.

Deprecated

win.isClosable() macOS Windows

Returns Boolean - Whether the window can be manually closed by user.

On Linux always returns true.

Deprecated

win.setAlwaysOnTop(flag[, level][, relativeLevel])

• flag Boolean
• level String (optional) macOS Windows - Values include normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saver, and dock (Deprecated). The default is floating when flag is true. The level is reset to normal when the flag is false. Note that from floating to status included, the window is placed below the Dock on macOS and below the taskbar on Windows. From pop-up-menu to a higher it is shown above the Dock on macOS and above the taskbar on Windows. See the macOS docs for more details.
• relativeLevel Integer (optional) macOS - The number of layers higher to set this window relative to the given level. The default is 0. Note that Apple discourages setting levels higher than 1 above screen-saver.

Sets whether the window should show always on top of other windows. After setting this, the window is still a normal window, not a toolbox window which can not be focused on.

win.isAlwaysOnTop()

Returns Boolean - Whether the window is always on top of other windows.

win.moveTop()

Moves window to top(z-order) regardless of focus

win.center()

Moves window to the center of the screen.

win.setPosition(x, y[, animate])

• x Integer
• y Integer
• animate Boolean (optional) macOS

Moves window to x and y.

win.getPosition()

Returns Integer[] - Contains the window's current position.

win.setTitle(title)

• title String

Changes the title of native window to title.

win.getTitle()

Returns String - The title of the native window.

Note: The title of the web page can be different from the title of the native window.

win.setSheetOffset(offsetY[, offsetX]) macOS

• offsetY Float
• offsetX Float (optional)

Changes the attachment point for sheets on macOS. By default, sheets are attached just below the window frame, but you may want to display them beneath a HTML-rendered toolbar. For example:

const { BrowserWindow } = require('electron')
let win = new BrowserWindow()

let toolbarRect = document.getElementById('toolbar').getBoundingClientRect()
win.setSheetOffset(toolbarRect.height)

win.flashFrame(flag)

• flag Boolean

Starts or stops flashing the window to attract user's attention.

win.setSkipTaskbar(skip)

• skip Boolean

Makes the window not show in the taskbar.

win.setKiosk(flag)

• flag Boolean

Enters or leaves the kiosk mode.

win.isKiosk()

Returns Boolean - Whether the window is in kiosk mode.

win.getNativeWindowHandle()

Returns Buffer - The platform-specific handle of the window.

The native type of the handle is HWND on Windows, NSView* on macOS, and Window (unsigned long) on Linux.

win.hookWindowMessage(message, callback) Windows

• message Integer
• callback Function

Hooks a windows message. The callback is called when the message is received in the WndProc.

win.isWindowMessageHooked(message) Windows

• message Integer

Returns Boolean - true or false depending on whether the message is hooked.

win.unhookWindowMessage(message) Windows

• message Integer

Unhook the window message.

win.unhookAllWindowMessages() Windows

Unhooks all of the window messages.

win.setRepresentedFilename(filename) macOS

• filename String

Sets the pathname of the file the window represents, and the icon of the file will show in window's title bar.

win.getRepresentedFilename() macOS

Returns String - The pathname of the file the window represents.

win.setDocumentEdited(edited) macOS

• edited Boolean

Specifies whether the window’s document has been edited, and the icon in title bar will become gray when set to true.

win.isDocumentEdited() macOS

Returns Boolean - Whether the window's document has been edited.

win.focusOnWebView()

win.blurWebView()

win.capturePage([rect])

• rect Rectangle (optional) - The bounds to capture

Returns Promise<NativeImage> - Resolves with a NativeImage

Captures a snapshot of the page within rect. Omitting rect will capture the whole visible page.

win.loadURL(url[, options])

• url String

• options Object (optional)

  • httpReferrer (String | Referrer) (optional) - An HTTP Referrer URL.
  • userAgent String (optional) - A user agent originating the request.
  • extraHeaders String (optional) - Extra headers separated by "\n"
  • postData (UploadRawData[] | UploadFile[] | UploadBlob[]) (optional)
  • baseURLForDataURL String (optional) - Base URL (with trailing path separator) for files to be loaded by the data URL. This is needed only if the specified url is a data URL and needs to load other files.

Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).

Same as webContents.loadURL(url[, options]).

The url can be a remote address (e.g. http://) or a path to a local HTML file using the file:// protocol.

To ensure that file URLs are properly formatted, it is recommended to use Node's url.format method:

let url = require('url').format({
  protocol: 'file',
  slashes: true,
  pathname: require('path').join(__dirname, 'index.html')
})

win.loadURL(url)

You can load a URL using a POST request with URL-encoded data by doing the following:

win.loadURL('http://localhost:8000/post', {
  postData: [{
    type: 'rawData',
    bytes: Buffer.from('hello=world')
  }],
  extraHeaders: 'Content-Type: application/x-www-form-urlencoded'
})

win.loadFile(filePath[, options])

• filePath String

• options Object (optional)

  • query Record<String, String> (optional) - Passed to url.format().
  • search String (optional) - Passed to url.format().
  • hash String (optional) - Passed to url.format().

Returns Promise<void> - the promise will resolve when the page has finished loading (see did-finish-load), and rejects if the page fails to load (see did-fail-load).

Same as webContents.loadFile, filePath should be a path to an HTML file relative to the root of your application. See the webContents docs for more information.

win.reload()

Same as webContents.reload.

win.setMenu(menu) Linux Windows

• menu Menu | null

Sets the menu as the window's menu bar.

win.removeMenu() Linux Windows

Remove the window's menu bar.

win.setProgressBar(progress[, options])

• progress Double

• options Object (optional)

  • mode String Windows - Mode for the progress bar. Can be none, normal, indeterminate, error or paused.

Sets progress value in progress bar. Valid range is [0, 1.0].

Remove progress bar when progress < 0; Change to indeterminate mode when progress > 1.

On Linux platform, only supports Unity desktop environment, you need to specify the *.desktop file name to desktopName field in package.json. By default, it will assume {app.name}.desktop.

On Windows, a mode can be passed. Accepted values are none, normal, indeterminate, error, and paused. If you call setProgressBar without a mode set (but with a value within the valid range), normal will be assumed.

win.setOverlayIcon(overlay, description) Windows

• overlay NativeImage | null - the icon to display on the bottom right corner of the taskbar icon. If this parameter is null, the overlay is cleared
• description String - a description that will be provided to Accessibility screen readers

Sets a 16 x 16 pixel overlay onto the current taskbar icon, usually used to convey some sort of application status or to passively notify the user.

win.setHasShadow(hasShadow)

• hasShadow Boolean

Sets whether the window should have a shadow.

win.hasShadow()

Returns Boolean - Whether the window has a shadow.

win.setOpacity(opacity) Windows macOS

• opacity Number - between 0.0 (fully transparent) and 1.0 (fully opaque)

Sets the opacity of the window. On Linux, does nothing. Out of bound number values are clamped to the [0, 1] range.

win.getOpacity()

Returns Number - between 0.0 (fully transparent) and 1.0 (fully opaque). On Linux, always returns 1.

win.setShape(rects) Windows Linux Experimental

• rects Rectangle[] - Sets a shape on the window. Passing an empty list reverts the window to being rectangular.

Setting a window shape determines the area within the window where the system permits drawing and user interaction. Outside of the given region, no pixels will be drawn and no mouse events will be registered. Mouse events outside of the region will not be received by that window, but will fall through to whatever is behind the window.

win.setThumbarButtons(buttons) Windows

• buttons ThumbarButton[]

Returns Boolean - Whether the buttons were added successfully

Add a thumbnail toolbar with a specified set of buttons to the thumbnail image of a window in a taskbar button layout. Returns a Boolean object indicates whether the thumbnail has been added successfully.

The number of buttons in thumbnail toolbar should be no greater than 7 due to the limited room. Once you setup the thumbnail toolbar, the toolbar cannot be removed due to the platform's limitation. But you can call the API with an empty array to clean the buttons.

The buttons is an array of Button objects:

• Button Object

  • icon NativeImage - The icon showing in thumbnail toolbar.
  • click Function
  • tooltip String (optional) - The text of the button's tooltip.
  • flags String - Control specific states and behaviors of the button. By default, it is ['enabled'].

The flags is an array that can include following Strings:

• enabled - The button is active and available to the user.
• disabled - The button is disabled. It is present, but has a visual state indicating it will not respond to user action.
• dismissonclick - When the button is clicked, the thumbnail window closes immediately.
• nobackground - Do not draw a button border, use only the image.
• hidden - The button is not shown to the user.
• noninteractive - The button is enabled but not interactive; no pressed button state is drawn. This value is intended for instances where the button is used in a notification.

win.setThumbnailClip(region) Windows

• region Rectangle - Region of the window

Sets the region of the window to show as the thumbnail image displayed when hovering over the window in the taskbar. You can reset the thumbnail to be the entire window by specifying an empty region: { x: 0, y: 0, width: 0, height: 0 }.

win.setThumbnailToolTip(toolTip) Windows

• toolTip String

Sets the toolTip that is displayed when hovering over the window thumbnail in the taskbar.

win.setAppDetails(options) Windows

• options Object

  • appId String (optional) - Window's App User Model ID. It has to be set, otherwise the other options will have no effect.
  • appIconPath String (optional) - Window's Relaunch Icon.
  • appIconIndex Integer (optional) - Index of the icon in appIconPath. Ignored when appIconPath is not set. Default is 0.
  • relaunchCommand String (optional) - Window's Relaunch Command.
  • relaunchDisplayName String (optional) - Window's Relaunch Display Name.

Sets the properties for the window's taskbar button.

Note: relaunchCommand and relaunchDisplayName must always be set together. If one of those properties is not set, then neither will be used.

win.showDefinitionForSelection() macOS

Same as webContents.showDefinitionForSelection().

win.setIcon(icon) Windows Linux

• icon NativeImage | String

Changes window icon.

win.setWindowButtonVisibility(visible) macOS

• visible Boolean

Sets whether the window traffic light buttons should be visible.

This cannot be called when titleBarStyle is set to customButtonsOnHover.

win.setAutoHideMenuBar(hide)

• hide Boolean

Sets whether the window menu bar should hide itself automatically. Once set the menu bar will only show when users press the single Alt key.

If the menu bar is already visible, calling setAutoHideMenuBar(true) won't hide it immediately.

Deprecated

win.isMenuBarAutoHide()

Returns Boolean - Whether menu bar automatically hides itself.

Deprecated

win.setMenuBarVisibility(visible) Windows Linux

• visible Boolean

Sets whether the menu bar should be visible. If the menu bar is auto-hide, users can still bring up the menu bar by pressing the single Alt key.

win.isMenuBarVisible()

Returns Boolean - Whether the menu bar is visible.

win.setVisibleOnAllWorkspaces(visible[, options])

• visible Boolean

• options Object (optional)

  • visibleOnFullScreen Boolean (optional) macOS - Sets whether the window should be visible above fullscreen windows

Sets whether the window should be visible on all workspaces.

Note: This API does nothing on Windows.

win.isVisibleOnAllWorkspaces()

Returns Boolean - Whether the window is visible on all workspaces.

Note: This API always returns false on Windows.

win.setIgnoreMouseEvents(ignore[, options])

• ignore Boolean

• options Object (optional)

  • forward Boolean (optional) macOS Windows - If true, forwards mouse move messages to Chromium, enabling mouse related events such as mouseleave. Only used when ignore is true. If ignore is false, forwarding is always disabled regardless of this value.

Makes the window ignore all mouse events.

All mouse events happened in this window will be passed to the window below this window, but if this window has focus, it will still receive keyboard events.

win.setContentProtection(enable) macOS Windows

• enable Boolean

Prevents the window contents from being captured by other apps.

On macOS it sets the NSWindow's sharingType to NSWindowSharingNone. On Windows it calls SetWindowDisplayAffinity with WDA_MONITOR.

win.setFocusable(focusable) macOS Windows

• focusable Boolean

Changes whether the window can be focused.

On macOS it does not remove the focus from the window.

win.setParentWindow(parent)

• parent BrowserWindow | null

Sets parent as current window's parent window, passing null will turn current window into a top-level window.

win.getParentWindow()

Returns BrowserWindow - The parent window.

win.getChildWindows()

Returns BrowserWindow[] - All child windows.

win.setAutoHideCursor(autoHide) macOS

• autoHide Boolean

Controls whether to hide cursor when typing.

win.selectPreviousTab() macOS

Selects the previous tab when native tabs are enabled and there are other tabs in the window.

win.selectNextTab() macOS

Selects the next tab when native tabs are enabled and there are other tabs in the window.

win.mergeAllWindows() macOS

Merges all windows into one window with multiple tabs when native tabs are enabled and there is more than one open window.

win.moveTabToNewWindow() macOS

Moves the current tab into a new window if native tabs are enabled and there is more than one tab in the current window.

win.toggleTabBar() macOS

Toggles the visibility of the tab bar if native tabs are enabled and there is only one tab in the current window.

win.addTabbedWindow(browserWindow) macOS

• browserWindow BrowserWindow

Adds a window as a tab on this window, after the tab for the window instance.

win.setVibrancy(type) macOS

• type String | null - Can be appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light, ultra-dark, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, or under-page. See the macOS documentation for more details.

Adds a vibrancy effect to the browser window. Passing null or an empty string will remove the vibrancy effect on the window.

Note that appearance-based, light, dark, medium-light, and ultra-dark have been deprecated and will be removed in an upcoming version of macOS.

win.setTouchBar(touchBar) macOS Experimental

• touchBar TouchBar | null

Sets the touchBar layout for the current window. Specifying null or undefined clears the touch bar. This method only has an effect if the machine has a touch bar and is running on macOS 10.12.1+.

Note: The TouchBar API is currently experimental and may change or be removed in future Electron releases.

win.setBrowserView(browserView) Experimental

• browserView BrowserView | null - Attach browserView to win. If there is some other browserViews was attached they will be removed from this window.

win.getBrowserView() Experimental

Returns BrowserView | null - an BrowserView what is attached. Returns null if none is attached. Throw error if multiple BrowserViews is attached.

win.addBrowserView(browserView) Experimental

• browserView BrowserView

Replacement API for setBrowserView supporting work with multi browser views.

win.removeBrowserView(browserView) Experimental

• browserView BrowserView

win.getBrowserViews() Experimental

Returns BrowserView[] - an array of all BrowserViews that have been attached with addBrowserView or setBrowserView.

Note: The BrowserView API is currently experimental and may change or be removed in future Electron releases.

Class: BrowserWindowProxy

Manipulate the child browser window

Process: Renderer

The BrowserWindowProxy object is returned from window.open and provides limited functionality with the child window.

Instance Methods

The BrowserWindowProxy object has the following instance methods:

win.blur()

Removes focus from the child window.

win.close()

Forcefully closes the child window without calling its unload event.

win.eval(code)

• code String

Evaluates the code in the child window.

win.focus()

Focuses the child window (brings the window to front).

win.print()

Invokes the print dialog on the child window.

win.postMessage(message, targetOrigin)

• message any
• targetOrigin String

Sends a message to the child window with the specified origin or * for no origin preference.

In addition to these methods, the child window implements window.opener object with no properties and a single method.

Instance Properties

The BrowserWindowProxy object has the following instance properties:

win.closed

A Boolean that is set to true after the child window gets closed.

Build Instructions

Follow the guidelines below for building Electron.

Platform prerequisites

Check the build prerequisites for your platform before proceeding

• macOS
• Linux
• Windows

GN prerequisites

You'll need to install depot_tools, the toolset used for fetching Chromium and its dependencies.

Also, on Windows, you'll need to set the environment variable DEPOT_TOOLS_WIN_TOOLCHAIN=0. To do so, open Control Panel → System and Security → System → Advanced system settings and add a system variable DEPOT_TOOLS_WIN_TOOLCHAIN with value 0. This tells depot_tools to use your locally installed version of Visual Studio (by default, depot_tools will try to download a Google-internal version that only Googlers have access to).

Cached builds (optional step)

GIT_CACHE_PATH

If you plan on building Electron more than once, adding a git cache will speed up subsequent calls to gclient. To do this, set a GIT_CACHE_PATH environment variable:

$ export GIT_CACHE_PATH="${HOME}/.git_cache"
$ mkdir -p "${GIT_CACHE_PATH}"
# This will use about 16G.

sccache

Thousands of files must be compiled to build Chromium and Electron. You can avoid much of the wait by reusing Electron CI's build output via sccache. This requires some optional steps (listed below) and these two environment variables:

export SCCACHE_BUCKET="electronjs-sccache-ci"
export SCCACHE_TWO_TIER=true

Getting the code

$ mkdir electron-gn && cd electron-gn
$ gclient config --name "src/electron" --unmanaged https://github.com/electron/electron
$ gclient sync --with_branch_heads --with_tags
# This will take a while, go get a coffee.

Instead of https://github.com/electron/electron, you can use your own fork here (something like https://github.com/<username>/electron).

A note on pulling/pushing

If you intend to git pull or git push from the official electron repository in the future, you now need to update the respective folder's origin URLs.

$ cd src/electron
$ git remote remove origin
$ git remote add origin https://github.com/electron/electron
$ git checkout master
$ git branch --set-upstream-to=origin/master
$ cd -

📝 gclient works by checking a file called DEPS inside the src/electron folder for dependencies (like Chromium or Node.js). Running gclient sync -f ensures that all dependencies required to build Electron match that file.

So, in order to pull, you'd run the following commands:

$ cd src/electron
$ git pull
$ gclient sync -f

Building

$ cd src
$ export CHROMIUM_BUILDTOOLS_PATH=`pwd`/buildtools
# this next line is needed only if building with sccache
$ export GN_EXTRA_ARGS="${GN_EXTRA_ARGS} cc_wrapper=\"${PWD}/electron/external_binaries/sccache\""
$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\") $GN_EXTRA_ARGS"

Or on Windows (without the optional argument):

$ cd src
$ set CHROMIUM_BUILDTOOLS_PATH=%cd%\buildtools
$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\")"

This will generate a build directory out/Testing under src/ with the testing build configuration. You can replace Testing with another name, but it should be a subdirectory of out. Also you shouldn't have to run gn gen again—if you want to change the build arguments, you can run gn args out/Testing to bring up an editor.

To see the list of available build configuration options, run gn args out/Testing --list.

For generating Testing build config of Electron:

$ gn gen out/Testing --args="import(\"//electron/build/args/testing.gn\") $GN_EXTRA_ARGS"

For generating Release (aka "non-component" or "static") build config of Electron:

$ gn gen out/Release --args="import(\"//electron/build/args/release.gn\") $GN_EXTRA_ARGS"

To build, run ninja with the electron target: Nota Bene: This will also take a while and probably heat up your lap.

For the testing configuration:

$ ninja -C out/Testing electron

For the release configuration:

$ ninja -C out/Release electron

This will build all of what was previously 'libchromiumcontent' (i.e. the content/ directory of chromium and its dependencies, incl. WebKit and V8), so it will take a while.

To speed up subsequent builds, you can use sccache. Add the GN arg cc_wrapper = "sccache" by running gn args out/Testing to bring up an editor and adding a line to the end of the file.

The built executable will be under ./out/Testing:

$ ./out/Testing/Electron.app/Contents/MacOS/Electron
# or, on Windows
$ ./out/Testing/electron.exe
# or, on Linux
$ ./out/Testing/electron

Packaging

On linux, first strip the debugging and symbol information:

electron/script/strip-binaries.py -d out/Release

To package the electron build as a distributable zip file:

ninja -C out/Release electron:electron_dist_zip

Cross-compiling

To compile for a platform that isn't the same as the one you're building on, set the target_cpu and target_os GN arguments. For example, to compile an x86 target from an x64 host, specify target_cpu = "x86" in gn args.

$ gn gen out/Testing-x86 --args='... target_cpu = "x86"'

Not all combinations of source and target CPU/OS are supported by Chromium.

If you test other combinations and find them to work, please update this document :)

See the GN reference for allowable values of target_os and target_cpu.

Windows on Arm (experimental)

To cross-compile for Windows on Arm, follow Chromium's guide to get the necessary dependencies, SDK and libraries, then build with ELECTRON_BUILDING_WOA=1 in your environment before running gclient sync.

set ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags

Or (if using PowerShell):

$env:ELECTRON_BUILDING_WOA=1
gclient sync -f --with_branch_heads --with_tags

Next, run gn gen as above with target_cpu="arm64".

Tests

To run the tests, you'll first need to build the test modules against the same version of Node.js that was built as part of the build process. To generate build headers for the modules to compile against, run the following under src/ directory.

$ ninja -C out/Testing third_party/electron_node:headers

You can now run the tests.

If you're debugging something, it can be helpful to pass some extra flags to the Electron binary:

$ npm run test -- \
  --enable-logging -g 'BrowserWindow module'

Sharing the git cache between multiple machines

It is possible to share the gclient git cache with other machines by exporting it as SMB share on linux, but only one process/machine can be using the cache at a time. The locks created by git-cache script will try to prevent this, but it may not work perfectly in a network.

On Windows, SMBv2 has a directory cache that will cause problems with the git cache script, so it is necessary to disable it by setting the registry key

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Lanmanworkstation\Parameters\DirectoryCacheLifetime

to 0. More information: https://stackoverflow.com/a/9935126

This can be set quickly in powershell (ran as administrator):

New-ItemProperty -Path "HKLM:\System\CurrentControlSet\Services\Lanmanworkstation\Parameters" -Name DirectoryCacheLifetime -Value 0 -PropertyType DWORD -Force

Troubleshooting

Stale locks in the git cache

If gclient sync is interrupted while using the git cache, it will leave the cache locked. To remove the lock, pass the --ignore_locks argument to gclient sync.

I'm being asked for a username/password for chromium-internal.googlesource.com

If you see a prompt for Username for 'https://chrome-internal.googlesource.com': when running gclient sync on Windows, it's probably because the DEPOT_TOOLS_WIN_TOOLCHAIN environment variable is not set to 0. Open Control Panel → System and Security → System → Advanced system settings and add a system variable DEPOT_TOOLS_WIN_TOOLCHAIN with value 0. This tells depot_tools to use your locally installed version of Visual Studio (by default, depot_tools will try to download a Google-internal version that only Googlers have access to).

Build Instructions (Linux)

Follow the guidelines below for building Electron on Linux.

Prerequisites

• At least 25GB disk space and 8GB RAM.

• Python 2.7.x. Some distributions like CentOS 6.x still use Python 2.6.x so you may need to check your Python version with python -V.

  Please also ensure that your system and Python version support at least TLS 1.2. For a quick test, run the following script:

  $ npx @electron/check-python-tls

  If the script returns that your configuration is using an outdated security protocol, use your system's package manager to update Python to the latest version in the 2.7.x branch. Alternatively, visit https://www.python.org/downloads/ for detailed instructions.

• Node.js. There are various ways to install Node. You can download source code from nodejs.org and compile it. Doing so permits installing Node on your own home directory as a standard user. Or try repositories such as NodeSource.

• clang 3.4 or later.

• Development headers of GTK+ and libnotify.

On Ubuntu, install the following libraries:

$ sudo apt-get install build-essential clang libdbus-1-dev libgtk-3-dev \
                       libnotify-dev libgnome-keyring-dev \
                       libasound2-dev libcap-dev libcups2-dev libxtst-dev \
                       libxss1 libnss3-dev gcc-multilib g++-multilib curl \
                       gperf bison python-dbusmock openjdk-8-jre

On RHEL / CentOS, install the following libraries:

$ sudo yum install clang dbus-devel gtk3-devel libnotify-devel \
                   libgnome-keyring-devel xorg-x11-server-utils libcap-devel \
                   cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \
                   nss-devel python-dbusmock openjdk-8-jre

On Fedora, install the following libraries:

$ sudo dnf install clang dbus-devel gtk3-devel libnotify-devel \
                   libgnome-keyring-devel xorg-x11-server-utils libcap-devel \
                   cups-devel libXtst-devel alsa-lib-devel libXrandr-devel \
                   nss-devel python-dbusmock openjdk-8-jre

Other distributions may offer similar packages for installation via package managers such as pacman. Or one can compile from source code.

Cross compilation

If you want to build for an arm target you should also install the following dependencies:

$ sudo apt-get install libc6-dev-armhf-cross linux-libc-dev-armhf-cross \
                       g++-arm-linux-gnueabihf

Similarly for arm64, install the following:

$ sudo apt-get install libc6-dev-arm64-cross linux-libc-dev-arm64-cross \
                       g++-aarch64-linux-gnu

And to cross-compile for arm or ia32 targets, you should pass the target_cpu parameter to gn gen:

$ gn gen out/Testing --args='import(...) target_cpu="arm"'

Building

See Build Instructions: GN

Troubleshooting

Error While Loading Shared Libraries: libtinfo.so.5

Prebuilt clang will try to link to libtinfo.so.5. Depending on the host architecture, symlink to appropriate libncurses:

$ sudo ln -s /usr/lib/libncurses.so.5 /usr/lib/libtinfo.so.5

Advanced topics

The default building configuration is targeted for major desktop Linux distributions. To build for a specific distribution or device, the following information may help you.

Using system clang instead of downloaded clang binaries

By default Electron is built with prebuilt clang binaries provided by the Chromium project. If for some reason you want to build with the clang installed in your system, you can specify the clang_base_path argument in the GN args.

For example if you installed clang under /usr/local/bin/clang:

$ gn gen out/Testing --args='import("//electron/build/args/testing.gn") clang_base_path = "/usr/local/bin"'

Using compilers other than clang

Building Electron with compilers other than clang is not supported.

Build Instructions (macOS)

Follow the guidelines below for building Electron on macOS.

Prerequisites

• macOS >= 10.11.6
• Xcode >= 9.0.0
• node.js (external)
• Python 2.7 with support for TLS 1.2

Python

Please also ensure that your system and Python version support at least TLS 1.2. This depends on both your version of macOS and Python. For a quick test, run:

$ npx @electron/check-python-tls

If the script returns that your configuration is using an outdated security protocol, you can either update macOS to High Sierra or install a new version of Python 2.7.x. To upgrade Python, use Homebrew:

$ brew install python@2 && brew link python@2 --force

If you are using Python as provided by Homebrew, you also need to install the following Python modules:

• pyobjc

You can use pip to install it:

$ pip install pyobjc

macOS SDK

If you're developing Electron and don't plan to redistribute your custom Electron build, you may skip this section.

Official Electron builds are built with Xcode 9.4.1, and the MacOS 10.13 SDK. Building with a newer SDK works too, but the releases currently use the 10.13 SDK.

Building Electron

See Build Instructions: GN.

Build Instructions (Windows)

Follow the guidelines below for building Electron on Windows.

Prerequisites

• Windows 10 / Server 2012 R2 or higher

• Visual Studio 2017 15.7.2 or higher - download VS 2019 Community Edition for free

  • See the Chromium build documentation for more details on which Visual Studio components are required.

  • If your Visual Studio is installed in a directory other than the default, you'll need to set a few environment variables to point the toolchains to your installation path.

    • vs2019_install = DRIVE:\path\to\Microsoft Visual Studio\2019\Community, replacing 2019 and Community with your installed versions and replacing DRIVE: with the drive that Visual Studio is on. Often, this will be C:.
    • WINDOWSSDKDIR = DRIVE:\path\to\Windows Kits\10, replacing DRIVE: with the drive that Windows Kits is on. Often, this will be C:.

• Python 2.7.10 or higher

  • Contrary to the depot_tools setup instructions linked below, you will need to use your locally installed Python with at least version 2.7.10 (with support for TLS 1.2). To do so, make sure that in PATH, your locally installed Python comes before the depot_tools folder. Right now depot_tools still comes with Python 2.7.6, which will cause the gclient command to fail (see https://crbug.com/868864).
  • Python for Windows (pywin32) Extensions is also needed in order to run the build process.
• Node.js
• Git

• Debugging Tools for Windows of Windows SDK 10.0.15063.468 if you plan on creating a full distribution since symstore.exe is used for creating a symbol store from .pdb files.

  • Different versions of the SDK can be installed side by side. To install the SDK, open Visual Studio Installer, select Change → Individual Components, scroll down and select the appropriate Windows SDK to install. Another option would be to look at the Windows SDK and emulator archive and download the standalone version of the SDK respectively.
  • The SDK Debugging Tools must also be installed. If the Windows 10 SDK was installed via the Visual Studio installer, then they can be installed by going to: Control Panel → Programs → Programs and Features → Select the "Windows Software Development Kit" → Change → Change → Check "Debugging Tools For Windows" → Change. Or, you can download the standalone SDK installer and use it to install the Debugging Tools.

If you don't currently have a Windows installation, dev.microsoftedge.com has timebombed versions of Windows that you can use to build Electron.

Building Electron is done entirely with command-line scripts and cannot be done with Visual Studio. You can develop Electron with any editor but support for building with Visual Studio will come in the future.

Note: Even though Visual Studio is not used for building, it's still required because we need the build toolchains it provides.

Building

See Build Instructions: GN

32bit Build

To build for the 32bit target, you need to pass target_cpu = "x86" as a GN arg. You can build the 32bit target alongside the 64bit target by using a different output directory for GN, e.g. out/Release-x86, with different arguments.

$ gn gen out/Release-x86 --args="import(\"//electron/build/args/release.gn\") target_cpu=\"x86\""

The other building steps are exactly the same.

Visual Studio project

To generate a Visual Studio project, you can pass the --ide=vs2017 parameter to gn gen:

$ gn gen out/Testing --ide=vs2017

Troubleshooting

Command xxxx not found

If you encountered an error like Command xxxx not found, you may try to use the VS2015 Command Prompt console to execute the build scripts.

Fatal internal compiler error: C1001

Make sure you have the latest Visual Studio update installed.

LNK1181: cannot open input file 'kernel32.lib'

Try reinstalling 32bit Node.js.

Error: ENOENT, stat 'C:\Users\USERNAME\AppData\Roaming\npm'

Creating that directory should fix the problem:

$ mkdir ~\AppData\Roaming\npm

node-gyp is not recognized as an internal or external command

You may get this error if you are using Git Bash for building, you should use PowerShell or VS2015 Command Prompt instead.

cannot create directory at '...': Filename too long

node.js has some extremely long pathnames, and by default git on windows doesn't handle long pathnames correctly (even though windows supports them). This should fix it:

$ git config --system core.longpaths true

error: use of undeclared identifier 'DefaultDelegateCheckMode'

This can happen during build, when Debugging Tools for Windows has been installed with Windows Driver Kit. Uninstall Windows Driver Kit and install Debugging Tools with steps described above.

ImportError: No module named win32file

Make sure you have installed pywin32 with pip install pywin32.

Build Scripts Hang Until Keypress

This bug is a "feature" of Windows' command prompt. It happens when clicking inside the prompt window with QuickEdit enabled and is intended to allow selecting and copying output text easily. Since each accidental click will pause the build process, you might want to disable this feature in the command prompt properties.

Build System Overview

Electron uses GN for project generation and ninja for building. Project configurations can be found in the .gn and .gni files.

GN Files

The following gn files contain the main rules for building Electron:

• BUILD.gn defines how Electron itself is built and includes the default configurations for linking with Chromium.
• build/args/{debug,release,all}.gn contain the default build arguments for building Electron.

Component Build

Since Chromium is quite a large project, the final linking stage can take quite a few minutes, which makes it hard for development. In order to solve this, Chromium introduced the "component build", which builds each component as a separate shared library, making linking very quick but sacrificing file size and performance.

Electron inherits this build option from Chromium. In Debug builds, the binary will be linked to a shared library version of Chromium's components to achieve fast linking time; for Release builds, the binary will be linked to the static library versions, so we can have the best possible binary size and performance.

Tests

NB this section is out of date and contains information that is no longer relevant to the GN-built electron.

Test your changes conform to the project coding style using:

$ npm run lint

Test functionality using:

$ npm test

Whenever you make changes to Electron source code, you'll need to re-run the build before the tests:

$ npm run build && npm test

You can make the test suite run faster by isolating the specific test or block you're currently working on using Mocha's exclusive tests feature. Append .only to any describe or it function call:

describe.only('some feature', () => {
  // ... only tests in this block will be run
})

Alternatively, you can use mocha's grep option to only run tests matching the given regular expression pattern:

$ npm test -- --grep child_process

Tests that include native modules (e.g. runas) can't be executed with the debug build (see #2558 for details), but they will work with the release build.

To run the tests with the release build use:

$ npm test -- -R

Certificate Object

• data String - PEM encoded data
• issuer CertificatePrincipal - Issuer principal
• issuerName String - Issuer's Common Name
• issuerCert Certificate - Issuer certificate (if not self-signed)
• subject CertificatePrincipal - Subject principal
• subjectName String - Subject's Common Name
• serialNumber String - Hex value represented string
• validStart Number - Start date of the certificate being valid in seconds
• validExpiry Number - End date of the certificate being valid in seconds
• fingerprint String - Fingerprint of the certificate

CertificatePrincipal Object

• commonName String - Common Name.
• organizations String[] - Organization names.
• organizationUnits String[] - Organization Unit names.
• locality String - Locality.
• state String - State or province.
• country String - Country or region.

Supported Chrome Command Line Switches

Command line switches supported by Electron.

You can use app.commandLine.appendSwitch to append them in your app's main script before the ready event of the app module is emitted:

const { app } = require('electron')
app.commandLine.appendSwitch('remote-debugging-port', '8315')
app.commandLine.appendSwitch('host-rules', 'MAP * 127.0.0.1')

app.on('ready', () => {
  // Your code here
})

--ignore-connections-limit=domains

Ignore the connections limit for domains list separated by ,.

--disable-http-cache

Disables the disk cache for HTTP requests.

--disable-http2

Disable HTTP/2 and SPDY/3.1 protocols.

--lang

Set a custom locale.

--inspect=port and --inspect-brk=port

Debug-related flags, see the Debugging the Main Process guide for details.

--remote-debugging-port=port

Enables remote debugging over HTTP on the specified port.

--disk-cache-size=size

Forces the maximum disk space to be used by the disk cache, in bytes.

--js-flags=flags

Specifies the flags passed to the Node.js engine. It has to be passed when starting Electron if you want to enable the flags in the main process.

$ electron --js-flags="--harmony_proxies --harmony_collections" your-app

See the Node.js documentation or run node --help in your terminal for a list of available flags. Additionally, run node --v8-options to see a list of flags that specifically refer to Node.js's V8 JavaScript engine.

--proxy-server=address:port

Use a specified proxy server, which overrides the system setting. This switch only affects requests with HTTP protocol, including HTTPS and WebSocket requests. It is also noteworthy that not all proxy servers support HTTPS and WebSocket requests. The proxy URL does not support username and password authentication per Chromium issue.

--proxy-bypass-list=hosts

Instructs Electron to bypass the proxy server for the given semi-colon-separated list of hosts. This flag has an effect only if used in tandem with --proxy-server.

For example:

const { app } = require('electron')
app.commandLine.appendSwitch('proxy-bypass-list', '<local>;*.google.com;*foo.com;1.2.3.4:5678')

Will use the proxy server for all hosts except for local addresses (localhost, 127.0.0.1 etc.), google.com subdomains, hosts that contain the suffix foo.com and anything at 1.2.3.4:5678.

--proxy-pac-url=url

Uses the PAC script at the specified url.

--no-proxy-server

Don't use a proxy server and always make direct connections. Overrides any other proxy server flags that are passed.

--host-rules=rules

A comma-separated list of rules that control how hostnames are mapped.

For example:

• MAP * 127.0.0.1 Forces all hostnames to be mapped to 127.0.0.1
• MAP *.google.com proxy Forces all google.com subdomains to be resolved to "proxy".
• MAP test.com [::1]:77 Forces "test.com" to resolve to IPv6 loopback. Will also force the port of the resulting socket address to be 77.
• MAP * baz, EXCLUDE www.google.com Remaps everything to "baz", except for "www.google.com".

These mappings apply to the endpoint host in a net request (the TCP connect and host resolver in a direct connection, and the CONNECT in an HTTP proxy connection, and the endpoint host in a SOCKS proxy connection).

--host-resolver-rules=rules

Like --host-rules but these rules only apply to the host resolver.

--auth-server-whitelist=url

A comma-separated list of servers for which integrated authentication is enabled.

For example:

--auth-server-whitelist='*example.com, *foobar.com, *baz'

then any url ending with example.com, foobar.com, baz will be considered for integrated authentication. Without * prefix the URL has to match exactly.

--auth-negotiate-delegate-whitelist=url

A comma-separated list of servers for which delegation of user credentials is required. Without * prefix the URL has to match exactly.

--ignore-certificate-errors

Ignores certificate related errors.

--ppapi-flash-path=path

Sets the path of the pepper flash plugin.

--ppapi-flash-version=version

Sets the version of the pepper flash plugin.

--log-net-log=path

Enables net log events to be saved and writes them to path.

--disable-renderer-backgrounding

Prevents Chromium from lowering the priority of invisible pages' renderer processes.

This flag is global to all renderer processes, if you only want to disable throttling in one window, you can take the hack of playing silent audio.

--enable-logging

Prints Chromium's logging into console.

This switch can not be used in app.commandLine.appendSwitch since it is parsed earlier than user's app is loaded, but you can set the ELECTRON_ENABLE_LOGGING environment variable to achieve the same effect.

--v=log_level

Gives the default maximal active V-logging level; 0 is the default. Normally positive values are used for V-logging levels.

This switch only works when --enable-logging is also passed.

--vmodule=pattern

Gives the per-module maximal V-logging levels to override the value given by --v. E.g. my_module=2,foo*=3 would change the logging level for all code in source files my_module.* and foo*.*.

Any pattern containing a forward or backward slash will be tested against the whole pathname and not only the module. E.g. */foo/bar/*=2 would change the logging level for all code in the source files under a foo/bar directory.

This switch only works when --enable-logging is also passed.

--no-sandbox

Disables Chromium sandbox, which is now enabled by default. Should only be used for testing.

Chromium Development

A collection of resources for learning about Chromium and tracking its development

• @ChromiumDev on Twitter
• @googlechrome on Twitter
• Blog
• Code Search
• Source Code
• Development Calendar and Release Info
• Discussion Groups

See also V8 Development

Using clang-format on C++ Code

clang-format is a tool to automatically format C/C++/Objective-C code, so that developers don't need to worry about style issues during code reviews.

It is highly recommended to format your changed C++ code before opening pull requests, which will save you and the reviewers' time.

You can install clang-format and git-clang-format via npm install -g clang-format.

To automatically format a file according to Electron C++ code style, run clang-format -i path/to/electron/file.cc. It should work on macOS/Linux/Windows.

The workflow to format your changed code:

1. Make codes changes in Electron repository.
2. Run git add your_changed_file.cc.
3. Run git-clang-format, and you will probably see modifications in your_changed_file.cc, these modifications are generated from clang-format.
4. Run git add your_changed_file.cc, and commit your change.
5. Now the branch is ready to be opened as a pull request.

If you want to format the changed code on your latest git commit (HEAD), you can run git-clang-format HEAD~1. See git-clang-format -h for more details.

Editor Integration

You can also integrate clang-format directly into your favorite editors. For further guidance on setting up editor integration, see these pages:

• Atom
• Vim & Emacs
• Visual Studio Code

Class: ClientRequest

Make HTTP/HTTPS requests.

Process: Main

ClientRequest implements the Writable Stream interface and is therefore an EventEmitter.

new ClientRequest(options)

• options (Object | String) - If options is a String, it is interpreted as the request URL. If it is an object, it is expected to fully specify an HTTP request via the following properties:

  • method String (optional) - The HTTP request method. Defaults to the GET method.
  • url String (optional) - The request URL. Must be provided in the absolute form with the protocol scheme specified as http or https.
  • session Session (optional) - The Session instance with which the request is associated.
  • partition String (optional) - The name of the partition with which the request is associated. Defaults to the empty string. The session option prevails on partition. Thus if a session is explicitly specified, partition is ignored.
  • protocol String (optional) - The protocol scheme in the form 'scheme:'. Currently supported values are 'http:' or 'https:'. Defaults to 'http:'.
  • host String (optional) - The server host provided as a concatenation of the hostname and the port number 'hostname:port'.
  • hostname String (optional) - The server host name.
  • port Integer (optional) - The server's listening port number.
  • path String (optional) - The path part of the request URL.
  • redirect String (optional) - The redirect mode for this request. Should be one of follow, error or manual. Defaults to follow. When mode is error, any redirection will be aborted. When mode is manual the redirection will be cancelled unless request.followRedirect is invoked synchronously during the redirect event.

options properties such as protocol, host, hostname, port and path strictly follow the Node.js model as described in the URL module.

For instance, we could have created the same request to 'github.com' as follows:

const request = net.request({
  method: 'GET',
  protocol: 'https:',
  hostname: 'github.com',
  port: 443,
  path: '/'
})

Instance Events

Event: 'response'

Returns:

• response IncomingMessage - An object representing the HTTP response message.

Event: 'login'

Returns:

• authInfo Object

  • isProxy Boolean
  • scheme String
  • host String
  • port Integer
  • realm String

• callback Function

  • username String (optional)
  • password String (optional)

Emitted when an authenticating proxy is asking for user credentials.

The callback function is expected to be called back with user credentials:

• username String
• password String

request.on('login', (authInfo, callback) => {
  callback('username', 'password')
})

Providing empty credentials will cancel the request and report an authentication error on the response object:

request.on('response', (response) => {
  console.log(`STATUS: ${response.statusCode}`);
  response.on('error', (error) => {
    console.log(`ERROR: ${JSON.stringify(error)}`)
  })
})
request.on('login', (authInfo, callback) => {
  callback()
})

Event: 'finish'

Emitted just after the last chunk of the request's data has been written into the request object.

Event: 'abort'

Emitted when the request is aborted. The abort event will not be fired if the request is already closed.

Event: 'error'

Returns:

• error Error - an error object providing some information about the failure.

Emitted when the net module fails to issue a network request. Typically when the request object emits an error event, a close event will subsequently follow and no response object will be provided.

Event: 'close'

Emitted as the last event in the HTTP request-response transaction. The close event indicates that no more events will be emitted on either the request or response objects.

Event: 'redirect'

Returns:

• statusCode Integer
• method String
• redirectUrl String
• responseHeaders Record<String, String[]>

Emitted when the server returns a redirect response (e.g. 301 Moved Permanently). Calling request.followRedirect will continue with the redirection. If this event is handled, request.followRedirect must be called synchronously, otherwise the request will be cancelled.

Instance Properties

request.chunkedEncoding

A Boolean specifying whether the request will use HTTP chunked transfer encoding or not. Defaults to false. The property is readable and writable, however it can be set only before the first write operation as the HTTP headers are not yet put on the wire. Trying to set the chunkedEncoding property after the first write will throw an error.

Using chunked encoding is strongly recommended if you need to send a large request body as data will be streamed in small chunks instead of being internally buffered inside Electron process memory.

Instance Methods

request.setHeader(name, value)

• name String - An extra HTTP header name.
• value String - An extra HTTP header value.

Adds an extra HTTP header. The header name will be issued as-is without lowercasing. It can be called only before first write. Calling this method after the first write will throw an error. If the passed value is not a String, its toString() method will be called to obtain the final value.

request.getHeader(name)

• name String - Specify an extra header name.

Returns String - The value of a previously set extra header name.

request.removeHeader(name)

• name String - Specify an extra header name.

Removes a previously set extra header name. This method can be called only before first write. Trying to call it after the first write will throw an error.

request.write(chunk[, encoding][, callback])

• chunk (String | Buffer) - A chunk of the request body's data. If it is a string, it is converted into a Buffer using the specified encoding.
• encoding String (optional) - Used to convert string chunks into Buffer objects. Defaults to 'utf-8'.
• callback Function (optional) - Called after the write operation ends.

callback is essentially a dummy function introduced in the purpose of keeping similarity with the Node.js API. It is called asynchronously in the next tick after chunk content have been delivered to the Chromium networking layer. Contrary to the Node.js implementation, it is not guaranteed that chunk content have been flushed on the wire before callback is called.

Adds a chunk of data to the request body. The first write operation may cause the request headers to be issued on the wire. After the first write operation, it is not allowed to add or remove a custom header.

request.end([chunk][, encoding][, callback])

• chunk (String | Buffer) (optional)
• encoding String (optional)
• callback Function (optional)

Sends the last chunk of the request data. Subsequent write or end operations will not be allowed. The finish event is emitted just after the end operation.

request.abort()

Cancels an ongoing HTTP transaction. If the request has already emitted the close event, the abort operation will have no effect. Otherwise an ongoing event will emit abort and close events. Additionally, if there is an ongoing response object,it will emit the aborted event.

request.followRedirect()

Continues any pending redirection. Can only be called during a 'redirect' event.

request.getUploadProgress()

Returns Object:

• active Boolean - Whether the request is currently active. If this is false no other properties will be set
• started Boolean - Whether the upload has started. If this is false both current and total will be set to 0.
• current Integer - The number of bytes that have been uploaded so far
• total Integer - The number of bytes that will be uploaded this request

You can use this method in conjunction with POST requests to get the progress of a file upload or other data transfer.

clipboard

Perform copy and paste operations on the system clipboard.

Process: Main, Renderer

On Linux, there is also a selection clipboard. To manipulate it you need to pass selection to each method:

const { clipboard } = require('electron')

clipboard.writeText('Example String', 'selection')
console.log(clipboard.readText('selection'))

Methods

The clipboard module has the following methods:

Note: Experimental APIs are marked as such and could be removed in future.

clipboard.readText([type])

• type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.

Returns String - The content in the clipboard as plain text.

const { clipboard } = require('electron')

clipboard.writeText('hello i am a bit of text!')

const text = clipboard.readText()
console.log(text)
// hello i am a bit of text!'

clipboard.writeText(text[, type])

• text String
• type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.

Writes the text into the clipboard as plain text.

const { clipboard } = require('electron')

const text = 'hello i am a bit of text!'
clipboard.writeText(text)

clipboard.readHTML([type])

• type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.

Returns String - The content in the clipboard as markup.

const { clipboard } = require('electron')

clipboard.writeHTML('<b>Hi</b>')
const html = clipboard.readHTML()

console.log(html)
// <meta charset='utf-8'><b>Hi</b>

clipboard.writeHTML(markup[, type])

• markup String
• type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.

Writes markup to the clipboard.

const { clipboard } = require('electron')

clipboard.writeHTML('<b>Hi</b')

clipboard.readImage([type])

• type String (optional) - Can be selection or clipboard; default is 'clipboard'. selection is only available on Linux.