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 key codes, 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

• to 9
• A to Z
• F1 to F24
• Punctuations like ~, !, @, #, $, etc.
• Plus
• Space
• Tab
• 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

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 just do everything in the ready event handler.

Event: 'ready'

Returns:

• launchInfo Object 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 behaviour, 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 Object - 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 Object - 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 Object - 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

• request Object

  • method String
  • url URL
  • referrer URL

• authInfo Object

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

• callback Function

  • username String
  • password String

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, request, authInfo, callback) => {
      event.preventDefault()
      callback('username', 'secret')
    })

Event: 'gpu-process-crashed'

Returns:

• event Event
• killed Boolean

Emitted when the gpu process 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.

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 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.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.getAppPath()

Returns String - The current application directory.

app.getPath(name)

• name String

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

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.
• 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.

app.getFileIcon(path[, options], callback)

• path String

• options Object (optional)

  • size String

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

• callback Function

  • error Error
  • icon 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, the directory will be created by this method. On failure an Error is thrown.

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 lowercased 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.setName(name)

• name String

Overrides the current application's name.

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.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.

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]) 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

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 JumpList 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[] or 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.makeSingleInstance(callback)

• callback Function

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

Returns Boolean.

This method makes your application a Single Instance Application - instead of allowing multiple instances of your app to run, this will ensure that only a single instance of your app is running, and other instances signal this instance and exit.

callback will be called by the first instance with callback(argv, workingDirectory) when a second instance has been executed. 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.

The callback is guaranteed to be executed after the ready event of app gets emitted.

This method returns false if your process is the primary instance of the application and your app should continue loading. And returns true if your process has sent its parameters to another instance, and you should immediately quit.

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 isSecondInstance = app.makeSingleInstance((commandLine, workingDirectory) => {
      // Someone tried to run a second instance, we should focus our window.
      if (myWindow) {
        if (myWindow.isMinimized()) myWindow.restore()
        myWindow.focus()
      }
    })
    
    if (isSecondInstance) {
      app.quit()
    }
    
    // Create myWindow, load the rest of the app, etc...
    app.on('ready', () => {
    })

app.releaseSingleInstance()

Releases all locks that were created by makeSingleInstance. 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 Object - 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

• type String - Uniquely identifies the activity. Maps to NSUserActivity.activityType.

Invalidates the current Handoff user activity.

app.updateCurrentActivity(type, userInfo) macOS

• type String - Uniquely identifies the activity. Maps to NSUserActivity.activityType.
• userInfo Object - 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 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/.

app.setBadgeCount(count) Linux macOS

• count Integer

Returns Boolean - Whether the call succeeded.

Sets the counter badge for current app. Setting the count to 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.

app.getBadgeCount() Linux macOS

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

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.getLoginItemStatus().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.

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. https://www.chromium.org/developers/design-documents/accessibility for more details. Disabled by default.

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

app.setAboutPanelOptions(options) macOS

• options Object

  • applicationName String (optional) - The app's name.
  • applicationVersion String (optional) - The app's version.
  • copyright String (optional) - Copyright information.
  • credits String (optional) - Credit information.
  • version String (optional) - The app's build version number.

Set the about panel options. This will override the values defined in the app's .plist file. See the Apple docs for more details.

app.startAccessingSecurityScopedResource(bookmarkData) macOS (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 
    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.commandLine.appendSwitch(switch[, value])

• switch String - A command-line switch
• value String (optional) - A value for the given switch

Append a switch (with optional value) to Chromium's command line.

Note: This will not affect process.argv, and is mainly used by developers to control some low-level Chromium behaviors.

app.commandLine.appendArgument(value)

• value String - The argument to append to the command line

Append an argument to Chromium's command line. The argument will be quoted correctly.

Note: This will not affect process.argv.

app.enableMixedSandbox() Experimental macOS Windows

Enables mixed 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() macOS

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

app.dock.bounce([type]) macOS

• type String (optional) - Can be critical or informational. The default is informational

When critical is passed, the dock icon will bounce until either the application becomes active or the request is canceled.

When informational is passed, the dock icon will bounce for one second. However, the request remains active until either the application becomes active or the request is canceled.

Returns Integer an ID representing the request.

app.dock.cancelBounce(id) macOS

• id Integer

Cancel the bounce of id.

app.dock.downloadFinished(filePath) macOS

• filePath String

Bounces the Downloads stack if the filePath is inside the Downloads folder.

app.dock.setBadge(text) macOS

• text String

Sets the string to be displayed in the dock’s badging area.

app.dock.getBadge() macOS

Returns String - The badge string of the dock.

app.dock.hide() macOS

Hides the dock icon.

app.dock.show() macOS

Shows the dock icon.

app.dock.isVisible() macOS

Returns Boolean - Whether the dock icon is visible. The app.dock.show() call is asynchronous so this method might not return true immediately after that call.

app.dock.setMenu(menu) macOS

• menu Menu

Sets the application's dock menu.

app.dock.setIcon(image) macOS

• image (NativeImage | String)

Sets the image associated with this dock icon.

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. Like 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 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 EH.app
        |   ├── Info.plist
        |   └── MacOS/
        |       └── MyApp Helper EH
        ├── MyApp Helper NP.app
        |   ├── Info.plist
        |   └── MacOS/
        |       └── MyApp Helper NP
        └── MyApp Helper.app
            ├── Info.plist
            └── MacOS/
                └── MyApp Helper

Linux

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

Packaging Tools

Apart from packaging your app manually, you can also choose to use third party packaging tools to do the work for you:

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

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 modify the atom.gyp file and have a clean 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:

   - atom-shell/
         - 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

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

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

3. 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

You can find a detailed guide about how to implement updates into your application here.

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.

Methods

The autoUpdater object has the following methods:

autoUpdater.setFeedURL(options)

• options Object

  • url String
  • headers Object (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: If the application is quit without calling this API after the update-downloaded event has been emitted, the application will still be replaced by the updated one on the next run.

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 nodejs' child_process API. The test suite will spawn the Electron process, then establish a simple messaging protocol:

var childProcess = require('child_process')
    var electronPath = require('electron')
    
    // spawn the process
    var env = { /* ... */ }
    var stdio = ['inherit', 'inherit', 'inherit', 'ipc']
    var 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 nodejs 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
          var 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
        var 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}) {
      var method = METHODS[cmd]
      if (!method) method = () => new Error('Invalid method: ' + cmd)
      try {
        var resolve = await method(...args)
        process.send({msgId, resolve})
      } catch (err) {
        var 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:

var test = require('ava')
    var electronPath = require('electron')
    
    var 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()
    })

BluetoothDevice Object

• deviceName String
• deviceId String

Boilerplates and CLIs

Electron development is un-opinionated - 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 ready-to-use templates for popular frameworks like React, Vue, or Angular. 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.

Class: BrowserView

Create and control views.

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

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({
      webPreferences: {
        nodeIntegration: false
      }
    })
    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 - If true, the view's width will grow and shrink together with the window. false by default.
  • height Boolean - If true, the view's height will grow and shrink together 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.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.

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 Windows it is not supported to change parent window dynamically.
• 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 .
  • minHeight Integer (optional) - Window's minimum height. Default is .
  • 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".
  • 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.
  • 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. Default is false.
  • backgroundColor String (optional) - Window's background color as a hexadecimal value, like #66CD00 or #FFF or #80FFFFFF (alpha is supported). 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.
  • 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, minimize, and full screen 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 or ultra-dark. Please note that using frame: false in combination with a vibrancy value requires that you use a non-default titleBarStyle as well.
  • 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 true.
    • nodeIntegrationInWorker Boolean (optional) - Whether node integration is enabled in web workers. Default is false. More about this can be found in Multithreading.
    • 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.
    • 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.
    • 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.
    • webaudio Boolean (optional) - Enables WebAudio 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.
    • experimentalCanvasFeatures Boolean (optional) - Enables Chromium's experimental canvas features. Default is false.
    • scrollBounce Boolean (optional) - Enables scroll bounce (rubber banding) effect on macOS. Default is false.
    • blinkFeatures 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 .
    • 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. Note: This option is currently experimental and may change or be removed in future Electron releases.
    • nativeWindowOpen Boolean (optional) - Whether to use native window.open(). Defaults to false. Note: This option is currently experimental.
    • webviewTag Boolean (optional) - Whether to enable the <webview> tag. Defaults to the value of the nodeIntegration option. 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.
    • additionArguments 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.

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

Emitted when the document changed its title, calling event.preventDefault() will prevent the native window's title from changing.

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 just 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.

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: 'resize'

Emitted when the window is being resized.

Event: 'move'

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

Note: On macOS this event is just 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: 'app-command' Windows

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()
      }
    })

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: '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 - 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 Object - 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 Object - 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

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

A Integer representing the unique ID of the window.

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.setAspectRatio(aspectRatio[, extraSize]) macOS

• aspectRatio Float - The aspect ratio to maintain for some portion of the content view.
• extraSize Size - 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. Just sum any extra width and height areas you have within the overall content view.

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 Rectangle
• animate Boolean (optional) macOS

Resizes and moves the window to the supplied bounds

win.getBounds()

Returns Rectangle

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

win.setEnabled(enable)

• enable Boolean

Disable or enable the window.

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

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

Resizes the window to width and height.

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.

win.isResizable()

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

win.setMovable(movable) macOS Windows

• movable Boolean

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

win.isMovable() macOS Windows

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

On Linux always returns true.

win.setMinimizable(minimizable) macOS Windows

• minimizable Boolean

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

win.isMinimizable() macOS Windows

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

On Linux always returns true.

win.setMaximizable(maximizable) macOS Windows

• maximizable Boolean

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

win.isMaximizable() macOS Windows

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

On Linux always returns true.

win.setFullScreenable(fullscreenable)

• fullscreenable Boolean

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

win.isFullScreenable()

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

win.setClosable(closable) macOS Windows

• closable Boolean

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

win.isClosable() macOS Windows

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

On Linux always returns true.

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

• flag Boolean
• level String (optional) macOS - Values include normal, floating, torn-off-menu, modal-panel, main-menu, status, pop-up-menu, screen-saver, and dock (Deprecated). The default is floating. 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 . 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.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 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, ]callback)

• rect Rectangle (optional) - The bounds to capture

• callback Function

  • image NativeImage

Same as webContents.capturePage([rect, ]callback).

win.loadURL(url[, options])

• url String

• options Object (optional)

  • httpReferrer String (optional) - A HTTP Referrer url.
  • userAgent String (optional) - A user agent originating the request.
  • extraHeaders String (optional) - Extra headers separated by "\n"
  • postData (UploadRawData[] | UploadFile[] | UploadFileSystem[] | 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.

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)

• filePath String

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, setting it to null will remove the 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.getName().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 - 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) macOS

• hasShadow Boolean

Sets whether the window should have a shadow. On Windows and Linux does nothing.

win.hasShadow() macOS

Returns Boolean - Whether the window has a shadow.

On Windows and Linux always returns true.

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.

win.getOpacity() Windows macOS

Returns Number - between 0.0 (fully transparent) and 1.0 (fully opaque)

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 .
  • 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

Changes window icon.

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.

win.isMenuBarAutoHide()

Returns Boolean - Whether menu bar automatically hides itself.

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)

• visible Boolean

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) 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) Windows

• focusable Boolean

Changes whether the window can be focused.

win.setParentWindow(parent) Linux macOS

• parent BrowserWindow

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 - Can be appearance-based, light, dark, titlebar, selection, menu, popover, sidebar, medium-light or ultra-dark. 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.

win.setTouchBar(touchBar) macOS Experimental

• touchBar TouchBar

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

win.getBrowserView() Experimental

Returns BrowserView | null - an attached BrowserView. Returns null if none is attached.

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 String
• 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 (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:

  $ python ./script/check-tls.py

  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 libgconf2-dev \
                           libasound2-dev libcap-dev libcups2-dev libxtst-dev \
                           libxss1 libnss3-dev gcc-multilib g++-multilib curl \
                           gperf bison

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 \
                       GConf2-devel nss-devel

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 \
                       GConf2-devel nss-devel

Other distributions may offer similar packages for installation via package managers such as pacman. Or one can compile from source code.

Getting the Code

$ git clone https://github.com/electron/electron

Bootstrapping

The bootstrap script will download all necessary build dependencies and create the build project files. You must have Python 2.7.x for the script to succeed. Downloading certain files can take a long time. Notice that we are using ninja to build Electron so there is no Makefile generated.

$ cd electron
    $ ./script/bootstrap.py --verbose

If you are using editor supports JSON compilation database based language server, you can generate it:

$ ./script/build.py --compdb

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_arch parameter to the bootstrap.py script:

$ ./script/bootstrap.py -v --target_arch=arm

Building

If you would like to build both Release and Debug targets:

$ ./script/build.py

This script will cause a very large Electron executable to be placed in the directory out/R. The file size is in excess of 1.3 gigabytes. This happens because the Release target binary contains debugging symbols. To reduce the file size, run the create-dist.py script:

$ ./script/create-dist.py

This will put a working distribution with much smaller file sizes in the dist directory. After running the create-dist.py script, you may want to remove the 1.3+ gigabyte binary which is still in out/R.

You can also build the Debug target only:

$ ./script/build.py -c D

After building is done, you can find the electron debug binary under out/D.

Cleaning

To clean the build files:

$ npm run clean

To clean only out and dist directories:

$ npm run clean-build

Note: Both clean commands require running bootstrap again before building.

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

Tests

See Build System Overview: Tests

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.

Building libchromiumcontent locally

To avoid using the prebuilt binaries of libchromiumcontent, you can build libchromiumcontent locally. To do so, follow these steps:

1. Install depot_tools
2. Install additional build dependencies
3. Fetch the git submodules:

$ git submodule update --init --recursive

1. Pass the --build_release_libcc switch to bootstrap.py script:

$ ./script/bootstrap.py -v --build_release_libcc

Note that by default the shared_library configuration is not built, so you can only build Release version of Electron if you use this mode:

$ ./script/build.py -c R

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 call bootstrap.py with --clang_dir=<path> switch. By passing it the build script will assume the clang binaries reside in <path>/bin/.

For example if you installed clang under /user/local/bin/clang:

$ ./script/bootstrap.py -v --build_release_libcc --clang_dir /usr/local
    $ ./script/build.py -c R

Using compilers other than clang

To build Electron with compilers like g++, you first need to disable clang with --disable_clang switch first, and then set CC and CXX environment variables to the ones you want.

For example building with GCC toolchain:

$ env CC=gcc CXX=g++ ./script/bootstrap.py -v --build_release_libcc --disable_clang
    $ ./script/build.py -c R

Environment variables

Apart from CC and CXX, you can also set the following environment variables to customise the build configuration:

• CPPFLAGS
• CPPFLAGS_host
• CFLAGS
• CFLAGS_host
• CXXFLAGS
• CXXFLAGS_host
• AR
• AR_host
• CC
• CC_host
• CXX
• CXX_host
• LDFLAGS

The environment variables have to be set when executing the bootstrap.py script, it won't work in the build.py script.

Build Instructions (macOS)

Follow the guidelines below for building Electron on macOS.

Prerequisites

• macOS >= 10.11.6
• Xcode >= 8.2.1
• 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:

$ python ./script/check-tls.py

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

macOS SDK

If you're developing Electron and don't plan to redistribute your custom Electron build, you may skip this section.

For certain features (e.g. pinch-zoom) to work properly, you must target the macOS 10.10 SDK.

Official Electron builds are built with Xcode 8.2.1, which does not contain the 10.10 SDK by default. To obtain it, first download and mount the Xcode 6.4 DMG.

Then, assuming that the Xcode 6.4 DMG has been mounted at /Volumes/Xcode and that your Xcode 8.2.1 install is at /Applications/Xcode.app, run:

cp -r /Volumes/Xcode/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/

You will also need to enable Xcode to build against the 10.10 SDK:

• Open /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Info.plist
• Set the MinimumSDKVersion to 10.10
• Save the file

Getting the Code

$ git clone https://github.com/electron/electron

Bootstrapping

The bootstrap script will download all necessary build dependencies and create the build project files. Notice that we're using ninja to build Electron so there is no Xcode project generated.

$ cd electron
    $ ./script/bootstrap.py -v

If you are using editor supports JSON compilation database based language server, you can generate it:

$ ./script/build.py --compdb

Building

Build both Release and Debug targets:

$ ./script/build.py

You can also only build the Debug target:

$ ./script/build.py -c D

After building is done, you can find Electron.app under out/D.

32bit Support

Electron can only be built for a 64bit target on macOS and there is no plan to support 32bit macOS in the future.

Cleaning

To clean the build files:

$ npm run clean

To clean only out and dist directories:

$ npm run clean-build

Note: Both clean commands require running bootstrap again before building.

Tests

See Build System Overview: Tests

Build Instructions (Windows)

Follow the guidelines below for building Electron on Windows.

Prerequisites

• Windows 7 / Server 2008 R2 or higher
• Visual Studio 2017 - download VS 2017 Community Edition for free
• Python 2.7
• Node.js
• Git
• Debugging Tools for Windows if you plan on creating a full distribution since symstore.exe is used for creating a symbol store from .pdb files.

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.

Getting the Code

$ git clone https://github.com/electron/electron.git

Bootstrapping

The bootstrap script will download all necessary build dependencies and create the build project files. Notice that we're using ninja to build Electron so there is no Visual Studio project generated.

$ cd electron
    $ python script\bootstrap.py -v

Building

Build both Release and Debug targets:

$ python script\build.py

You can also only build the Debug target:

$ python script\build.py -c D

After building is done, you can find electron.exe under out\D (debug target) or under out\R (release target).

32bit Build

To build for the 32bit target, you need to pass --target_arch=ia32 when running the bootstrap script:

$ python script\bootstrap.py -v --target_arch=ia32

The other building steps are exactly the same.

Visual Studio project

To generate a Visual Studio project, you can pass the --msvs parameter:

$ python script\bootstrap.py --msvs

Cleaning

To clean the build files:

$ npm run clean

To clean only out and dist directories:

$ npm run clean-build

Note: Both clean commands require running bootstrap again before building.

Tests

See Build System Overview: Tests

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.

Assertion failed: ((handle))->activecnt >= 0

If building under Cygwin, you may see bootstrap.py failed with following error:

Assertion failed: ((handle))->activecnt >= 0, file src\win\pipe.c, line 1430
    
    Traceback (most recent call last):
      File "script/bootstrap.py", line 87, in <module>
        sys.exit(main())
      File "script/bootstrap.py", line 22, in main
        update_node_modules('.')
      File "script/bootstrap.py", line 56, in update_node_modules
        execute([NPM, 'install'])
      File "/home/zcbenz/codes/raven/script/lib/util.py", line 118, in execute
        raise e
    subprocess.CalledProcessError: Command '['npm.cmd', 'install']' returned non-zero exit status 3

This is caused by a bug when using Cygwin Python and Win32 Node together. The solution is to use the Win32 Python to execute the bootstrap script (assuming you have installed Python under C:\Python27):

$ /cygdrive/c/Python27/python.exe script/bootstrap.py

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.

Build System Overview

Electron uses gyp for project generation and ninja for building. Project configurations can be found in the .gyp and .gypi files.

Gyp Files

Following gyp files contain the main rules for building Electron:

• electron.gyp defines how Electron itself is built.
• common.gypi adjusts the build configurations of Node to make it build together with Chromium.
• brightray/brightray.gyp defines how brightray is built and includes the default configurations for linking with Chromium.
• brightray/brightray.gypi includes general build configurations about building.

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.

In Electron we took a very similar approach: for 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.

Minimal Bootstrapping

All of Chromium's prebuilt binaries (libchromiumcontent) are downloaded when running the bootstrap script. By default both static libraries and shared libraries will be downloaded and the final size should be between 800MB and 2GB depending on the platform.

By default, libchromiumcontent is downloaded from Amazon Web Services. If the LIBCHROMIUMCONTENT_MIRROR environment variable is set, the bootstrap script will download from it. libchromiumcontent-qiniu-mirror is a mirror for libchromiumcontent. If you have trouble in accessing AWS, you can switch the download address to it via export LIBCHROMIUMCONTENT_MIRROR=http://7xk3d2.dl1.z0.glb.clouddn.com/

If you only want to build Electron quickly for testing or development, you can download the shared library versions by passing the --dev parameter:

$ ./script/bootstrap.py --dev
    $ ./script/build.py -c D

Two-Phase Project Generation

Electron links with different sets of libraries in Release and Debug builds. gyp, however, doesn't support configuring different link settings for different configurations.

To work around this Electron uses a gyp variable libchromiumcontent_component to control which link settings to use and only generates one target when running gyp.

Target Names

Unlike most projects that use Release and Debug as target names, Electron uses R and D instead. This is because gyp randomly crashes if there is only one Release or Debug build configuration defined, and Electron only has to generate one target at a time as stated above.

This only affects developers, if you are building Electron for rebranding you are not affected.

Tests

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', function () {
      // ... 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 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'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.

--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 just 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.

Chromium Development

A collection of resources for learning about Chromium and tracking its development

• chromiumdev on Slack
• @ChromiumDev on Twitter
• @googlechrome on Twitter
• Blog
• Code Search
• Source Code
• Development Calendar and Release Info
• Discussion Groups

See also V8 Development

Chromium development with Electron

It is possible to debug Chromium with Electron by passing --build_debug_libcc to the bootstrap script:

$ ./script/bootstrap.py -d --build_debug_libcc

This will download and build libchromiumcontent locally, similarly to the --build_release_libcc, but it will create a shared library build of libchromiumcontent and won't strip any symbols, making it ideal for debugging.

When built like this, you can make changes to files in vendor/libchromiumcontent/src and rebuild quickly with:

$ ./script/build.py -c D --libcc

When developing on linux with gdb, it is recommended to add a gdb index to speed up loading symbols. This doesn't need to be executed on every build, but it is recommended to do it at least once to index most shared libraries:

$ ./vendor/libchromiumcontent/src/build/gdb-add-index ./out/D/electron

Building libchromiumcontent requires a powerful machine and takes a long time (though incremental rebuilding the shared library component is fast). With an 8-core/16-thread Ryzen 1700 CPU clocked at 3ghz, fast SSD and 32GB of RAM, it should take about 40 minutes. It is not recommended to build with less than 16GB of RAM.

Chromium git cache

depot_tools has an undocumented option that allows the developer to set a global cache for all git objects of Chromium + dependencies. This option uses git clone --shared to save bandwidth/space on multiple clones of the same repositories.

On electron/libchromiumcontent, this option is exposed through the LIBCHROMIUMCONTENT_GIT_CACHE environment variable. If you intend to have several libchromiumcontent build trees on the same machine(to work on different branches for example), it is recommended to set the variable to speed up the download of Chromium source. For example:

$ mkdir ~/.chromium-git-cache
    $ LIBCHROMIUMCONTENT_GIT_CACHE=~/.chromium-git-cache ./script/bootstrap.py -d --build_debug_libcc

If the bootstrap script is interrupted while using the git cache, it will leave the cache locked. To remove the lock, delete the files ending in .lock:

$ find ~/.chromium-git-cache/ -type f -name '*.lock' -delete

It is possible to share this directory 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

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 Object (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 deferred until request.followRedirect is invoked. Listen for the redirect event in this mode to get more details about the redirect request.

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
  • password String

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 Object

Emitted when there is redirection and the mode is manual. Calling request.followRedirect will continue with the redirection.

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 Object - An extra HTTP header value.

Adds an extra HTTP header. The header name will issued as it 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 Object - 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 deferred redirection request when the redirection mode is manual.

clipboard

Perform copy and paste operations on the system clipboard.

Process: Main, Renderer

The following example shows how to write a string to the clipboard:

const {clipboard} = require('electron')
    clipboard.writeText('Example String')

On X Window systems, 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)

Returns String - The content in the clipboard as plain text.

clipboard.writeText(text[, type])

• text String
• type String (optional)

Writes the text into the clipboard as plain text.

clipboard.readHTML([type])

• type String (optional)

Returns String - The content in the clipboard as markup.

clipboard.writeHTML(markup[, type])

• markup String
• type String (optional)

Writes markup to the clipboard.

clipboard.readImage([type])

• type String (optional)

Returns NativeImage - The image content in the clipboard.

clipboard.writeImage(image[, type])

• image NativeImage
• type String (optional)

Writes image to the clipboard.

clipboard.readRTF([type])

• type String (optional)

Returns String - The content in the clipboard as RTF.

clipboard.writeRTF(text[, type])

• text String
• type String (optional)

Writes the text into the clipboard in RTF.

clipboard.readBookmark() macOS Windows

Returns Object:

• title String
• url String

Returns an Object containing title and url keys representing the bookmark in the clipboard. The title and url values will be empty strings when the bookmark is unavailable.

clipboard.writeBookmark(title, url[, type]) macOS Windows

• title String
• url String
• type String (optional)

Writes the title and url into the clipboard as a bookmark.

Note: Most apps on Windows don't support pasting bookmarks into them so you can use clipboard.write to write both a bookmark and fallback text to the clipboard.

clipboard.write({
      text: 'https://electronjs.org',
      bookmark: 'Electron Homepage'
    })

clipboard.readFindText() macOS

Returns String - The text on the find pasteboard. This method uses synchronous IPC when called from the renderer process. The cached value is reread from the find pasteboard whenever the application is activated.

clipboard.writeFindText(text) macOS

• text String

Writes the text into the find pasteboard as plain text. This method uses synchronous IPC when called from the renderer process.

clipboard.clear([type])

• type String (optional)

Clears the clipboard content.

clipboard.availableFormats([type])

• type String (optional)

Returns String[] - An array of supported formats for the clipboard type.

clipboard.has(format[, type]) Experimental

• format String
• type String (optional)

Returns Boolean - Whether the clipboard supports the specified format.

const {clipboard} = require('electron')
    console.log(clipboard.has('<p>selection</p>'))

clipboard.read(format) Experimental

• format String

Returns String - Reads format type from the clipboard.

clipboard.readBuffer(format) Experimental

• format String

Returns Buffer - Reads format type from the clipboard.

clipboard.writeBuffer(format, buffer[, type]) Experimental

• format String
• buffer Buffer
• type String (optional)

Writes the buffer into the clipboard as format.

clipboard.write(data[, type])

• data Object

  • text String (optional)
  • html String (optional)
  • image NativeImage (optional)
  • rtf String (optional)
  • bookmark String (optional) - The title of the url at text.
• type String (optional)

const {clipboard} = require('electron')
    clipboard.write({text: 'test', html: '<b>test</b>'})

Writes data to the clipboard.

Code Signing

Code signing is a security technology that you use to certify that an app was created by you.

On macOS the system can detect any change to the app, whether the change is introduced accidentally or by malicious code.

On Windows the system assigns a trust level to your code signing certificate which if you don't have, or if your trust level is low will cause security dialogs to appear when users start using your application. Trust level builds over time so it's better to start code signing as early as possible.

While it is possible to distribute unsigned apps, it is not recommended. For example, here's what macOS users see when attempting to start an unsigned app:

App can't be opened because it is from an unidentified developer

If you are building an Electron app that you intend to package and distribute, it should be code signed. The Mac and Windows app stores do not allow unsigned apps.

Signing macOS builds

Before signing macOS builds, you must do the following:

1. Enroll in the (requires an annual fee)
2. Download and install Xcode
3. Generate, download, and install signing certificates

There are a number of tools for signing your packaged app:

• [electron-osx-sign] is a standalone tool for signing macOS packages.

• [electron-packager] bundles electron-osx-sign. If you're using electron-packager, pass the --osx-sign=true flag to sign your build.

  • [electron-forge] uses electron-packager internally, you can set the osxSign option in your forge config.
• [electron-builder] has built-in code-signing capabilities. See electron.build/code-signing

For more info, see the Mac App Store Submission Guide.

Signing Windows builds

Before signing Windows builds, you must do the following:

1. Get a Windows Authenticode code signing certificate
2. Install Visual Studio 2015/2017 (to get the signing utility)

You can get a code signing certificate from a lot of resellers, popular ones include:

• digicert
• Comodo
• GoDaddy
• Amongst others, please shop around to find one that suits your needs, Google is your friend :)

There are a number of tools for signing your packaged app:

• [electron-winstaller] will generate an installer for windows and sign it for you
• [electron-forge] can sign installers it generates through the Squirrel.Windows or MSI targets.
• [electron-builder] can sign some of its windows targets

Windows Store

See the Windows Store Guide.

Coding Style

These are the style guidelines for coding in Electron.

You can run npm run lint to show any style issues detected by cpplint and eslint.

General Code

• End files with a newline.

• Place requires in the following order:

  • Built in Node Modules (such as path)
  • Built in Electron Modules (such as ipc, app)
  • Local Modules (using relative paths)

• Place class properties in the following order:

  • Class methods and properties (methods starting with a @)
  • Instance methods and properties

• Avoid platform-dependent code:

  • Use path.join() to concatenate filenames.
  • Use os.tmpdir() rather than /tmp when you need to reference the temporary directory.

• Using a plain return when returning explicitly at the end of a function.

  • Not return null, return undefined, null or undefined

C++ and Python

For C++ and Python, we follow Chromium's Coding Style. You can use clang-format to format the C++ code automatically. There is also a script script/cpplint.py to check whether all files conform.

The Python version we are using now is Python 2.7.

The C++ code uses a lot of Chromium's abstractions and types, so it's recommended to get acquainted with them. A good place to start is Chromium's Important Abstractions and Data Structures document. The document mentions some special types, scoped types (that automatically release their memory when going out of scope), logging mechanisms etc.

Documentation

• Write remark markdown style

You can run npm run lint-docs to ensure that your documentation changes are formatted correctly.

JavaScript

• Write standard JavaScript style.
• File names should be concatenated with - instead of _, e.g. file-name.js rather than file_name.js, because in github/atom module names are usually in the module-name form. This rule only applies to .js files.

• Use newer ES6/ES2015 syntax where appropriate

  • const for requires and other constants
  • let for defining variables
  • Arrow functions instead of function () { }
  • Template literals instead of string concatenation using +

Naming Things

Electron APIs uses the same capitalization scheme as Node.js:

• When the module itself is a class like BrowserWindow, use PascalCase.
• When the module is a set of APIs, like globalShortcut, use camelCase.
• When the API is a property of object, and it is complex enough to be in a separate chapter like win.webContents, use mixedCase.
• For other non-module APIs, use natural titles, like <webview> Tag or Process Object.

When creating a new API, it is preferred to use getters and setters instead of jQuery's one-function style. For example, .getText() and .setText(text) are preferred to .text([text]). There is a discussion on this.

contentTracing

Collect tracing data from Chromium's content module for finding performance bottlenecks and slow operations.

Process: Main

This module does not include a web interface so you need to open chrome://tracing/ in a Chrome browser and load the generated file to view the result.

Note: You should not use this module until the ready event of the app module is emitted.

const {app, contentTracing} = require('electron')
    
    app.on('ready', () => {
      const options = {
        categoryFilter: '*',
        traceOptions: 'record-until-full,enable-sampling'
      }
    
      contentTracing.startRecording(options, () => {
        console.log('Tracing started')
    
        setTimeout(() => {
          contentTracing.stopRecording('', (path) => {
            console.log('Tracing data recorded to ' + path)
          })
        }, 5000)
      })
    })

Methods

The contentTracing module has the following methods:

contentTracing.getCategories(callback)

• callback Function

  • categories String[]

Get a set of category groups. The category groups can change as new code paths are reached.

Once all child processes have acknowledged the getCategories request the callback is invoked with an array of category groups.

contentTracing.startRecording(options, callback)

• options Object

  • categoryFilter String
  • traceOptions String
• callback Function

Start recording on all processes.

Recording begins immediately locally and asynchronously on child processes as soon as they receive the EnableRecording request. The callback will be called once all child processes have acknowledged the startRecording request.

categoryFilter is a filter to control what category groups should be traced. A filter can have an optional - prefix to exclude category groups that contain a matching category. Having both included and excluded category patterns in the same list is not supported.

Examples:

• test_MyTest*,
• test_MyTest*,test_OtherStuff,
• "-excluded_category1,-excluded_category2

traceOptions controls what kind of tracing is enabled, it is a comma-delimited list. Possible options are:

• record-until-full
• record-continuously
• trace-to-console
• enable-sampling
• enable-systrace

The first 3 options are trace recording modes and hence mutually exclusive. If more than one trace recording modes appear in the traceOptions string, the last one takes precedence. If none of the trace recording modes are specified, recording mode is record-until-full.

The trace option will first be reset to the default option (record_mode set to record-until-full, enable_sampling and enable_systrace set to false) before options parsed from traceOptions are applied on it.

contentTracing.stopRecording(resultFilePath, callback)

• resultFilePath String

• callback Function

  • resultFilePath String

Stop recording on all processes.

Child processes typically cache trace data and only rarely flush and send trace data back to the main process. This helps to minimize the runtime overhead of tracing since sending trace data over IPC can be an expensive operation. So, to end tracing, we must asynchronously ask all child processes to flush any pending trace data.

Once all child processes have acknowledged the stopRecording request, callback will be called with a file that contains the traced data.

Trace data will be written into resultFilePath if it is not empty or into a temporary file. The actual file path will be passed to callback if it's not null.

contentTracing.startMonitoring(options, callback)

• options Object

  • categoryFilter String
  • traceOptions String
• callback Function

Start monitoring on all processes.

Monitoring begins immediately locally and asynchronously on child processes as soon as they receive the startMonitoring request.

Once all child processes have acknowledged the startMonitoring request the callback will be called.

contentTracing.stopMonitoring(callback)

• callback Function

Stop monitoring on all processes.

Once all child processes have acknowledged the stopMonitoring request the callback is called.

contentTracing.captureMonitoringSnapshot(resultFilePath, callback)

• resultFilePath String

• callback Function

  • resultFilePath String

Get the current monitoring traced data.

Child processes typically cache trace data and only rarely flush and send trace data back to the main process. This is because it may be an expensive operation to send the trace data over IPC and we would like to avoid unneeded runtime overhead from tracing. So, to end tracing, we must asynchronously ask all child processes to flush any pending trace data.

Once all child processes have acknowledged the captureMonitoringSnapshot request the callback will be called with a file that contains the traced data.

contentTracing.getTraceBufferUsage(callback)

• callback Function

  • value Number
  • percentage Number

Get the maximum usage across processes of trace buffer as a percentage of the full state. When the TraceBufferUsage value is determined the callback is called.

Cookie Object

• name String - The name of the cookie.
• value String - The value of the cookie.
• domain String (optional) - The domain of the cookie.
• hostOnly Boolean (optional) - Whether the cookie is a host-only cookie.
• path String (optional) - The path of the cookie.
• secure Boolean (optional) - Whether the cookie is marked as secure.
• httpOnly Boolean (optional) - Whether the cookie is marked as HTTP only.
• session Boolean (optional) - Whether the cookie is a session cookie or a persistent cookie with an expiration date.
• expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. Not provided for session cookies.

Class: Cookies

Query and modify a session's cookies.

Process: Main

Instances of the Cookies class are accessed by using cookies property of a Session.

For example:

const {session} = require('electron')
    
    // Query all cookies.
    session.defaultSession.cookies.get({}, (error, cookies) => {
      console.log(error, cookies)
    })
    
    // Query all cookies associated with a specific url.
    session.defaultSession.cookies.get({url: 'http://www.github.com'}, (error, cookies) => {
      console.log(error, cookies)
    })
    
    // Set a cookie with the given cookie data;
    // may overwrite equivalent cookies if they exist.
    const cookie = {url: 'http://www.github.com', name: 'dummy_name', value: 'dummy'}
    session.defaultSession.cookies.set(cookie, (error) => {
      if (error) console.error(error)
    })

Instance Events

The following events are available on instances of Cookies:

Event: 'changed'

• event Event
• cookie Cookie - The cookie that was changed.

• cause String - The cause of the change with one of the following values:

  • explicit - The cookie was changed directly by a consumer's action.
  • overwrite - The cookie was automatically removed due to an insert operation that overwrote it.
  • expired - The cookie was automatically removed as it expired.
  • evicted - The cookie was automatically evicted during garbage collection.
  • expired-overwrite - The cookie was overwritten with an already-expired expiration date.
• removed Boolean - true if the cookie was removed, false otherwise.

Emitted when a cookie is changed because it was added, edited, removed, or expired.

Instance Methods

The following methods are available on instances of Cookies:

cookies.get(filter, callback)

• filter Object

  • url String (optional) - Retrieves cookies which are associated with url. Empty implies retrieving cookies of all urls.
  • name String (optional) - Filters cookies by name.
  • domain String (optional) - Retrieves cookies whose domains match or are subdomains of domains.
  • path String (optional) - Retrieves cookies whose path matches path.
  • secure Boolean (optional) - Filters cookies by their Secure property.
  • session Boolean (optional) - Filters out session or persistent cookies.

• callback Function

  • error Error
  • cookies Cookie[] - an array of cookie objects.

Sends a request to get all cookies matching filter, callback will be called with callback(error, cookies) on complete.

cookies.set(details, callback)

• details Object

  • url String - The url to associate the cookie with.
  • name String (optional) - The name of the cookie. Empty by default if omitted.
  • value String (optional) - The value of the cookie. Empty by default if omitted.
  • domain String (optional) - The domain of the cookie. Empty by default if omitted.
  • path String (optional) - The path of the cookie. Empty by default if omitted.
  • secure Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to false.
  • httpOnly Boolean (optional) - Whether the cookie should be marked as HTTP only. Defaults to false.
  • expirationDate Double (optional) - The expiration date of the cookie as the number of seconds since the UNIX epoch. If omitted then the cookie becomes a session cookie and will not be retained between sessions.

• callback Function

  • error Error

Sets a cookie with details, callback will be called with callback(error) on complete.

cookies.remove(url, name, callback)

• url String - The URL associated with the cookie.
• name String - The name of cookie to remove.
• callback Function

Removes the cookies matching url and name, callback will called with callback() on complete.

cookies.flushStore(callback)

• callback Function

Writes any unwritten cookies data to disk.

CPUUsage Object

• percentCPUUsage Number - Percentage of CPU used since the last call to getCPUUsage. First call returns 0.
• idleWakeupsPerSecond Number - The number of average idle cpu wakeups per second since the last call to getCPUUsage. First call returns 0. Will always return 0 on Windows.

CrashReport Object

• date Date
• id String

crashReporter

Submit crash reports to a remote server.

Process: Main, Renderer

The following is an example of automatically submitting a crash report to a remote server:

const {crashReporter} = require('electron')
    
    crashReporter.start({
      productName: 'YourName',
      companyName: 'YourCompany',
      submitURL: 'https://your-domain.com/url-to-submit',
      uploadToServer: true
    })

For setting up a server to accept and process crash reports, you can use following projects:

• socorro
• mini-breakpad-server

Crash reports are saved locally in an application-specific temp directory folder. For a productName of YourName, crash reports will be stored in a folder named YourName Crashes inside the temp directory. You can customize this temp directory location for your app by calling the app.setPath('temp', '/my/custom/temp') API before starting the crash reporter.

Methods

The crashReporter module has the following methods:

crashReporter.start(options)

• options Object

  • companyName String (optional)
  • submitURL String - URL that crash reports will be sent to as POST.
  • productName String (optional) - Defaults to app.getName().
  • uploadToServer Boolean (optional) - Whether crash reports should be sent to the server Default is true.
  • ignoreSystemCrashHandler Boolean (optional) - Default is false.
  • extra Object (optional) - An object you can define that will be sent along with the report. Only string properties are sent correctly. Nested objects are not supported and the property names and values must be less than 64 characters long.
  • crashesDirectory String (optional) - Directory to store the crashreports temporarily (only used when the crash reporter is started via process.crashReporter.start).

You are required to call this method before using any other crashReporter APIs and in each process (main/renderer) from which you want to collect crash reports. You can pass different options to crashReporter.start when calling from different processes.

Note Child processes created via the child_process module will not have access to the Electron modules. Therefore, to collect crash reports from them, use process.crashReporter.start instead. Pass the same options as above along with an additional one called crashesDirectory that should point to a directory to store the crash reports temporarily. You can test this out by calling process.crash() to crash the child process.

Note: To collect crash reports from child process in Windows, you need to add this extra code as well. This will start the process that will monitor and send the crash reports. Replace submitURL, productName and crashesDirectory with appropriate values.

Note: If you need send additional/updated extra parameters after your first call start you can call addExtraParameter on macOS or call start again with the new/updated extra parameters on Linux and Windows.

 const args = [
       `--reporter-url=${submitURL}`,
       `--application-name=${productName}`,
       `--crashes-directory=${crashesDirectory}`
     ]
     const env = {
       ELECTRON_INTERNAL_CRASH_SERVICE: 1
     }
     spawn(process.execPath, args, {
       env: env,
       detached: true
     })

Note: On macOS, Electron uses a new crashpad client for crash collection and reporting. If you want to enable crash reporting, initializing crashpad from the main process using crashReporter.start is required regardless of which process you want to collect crashes from. Once initialized this way, the crashpad handler collects crashes from all processes. You still have to call crashReporter.start from the renderer or child process, otherwise crashes from them will get reported without companyName, productName or any of the extra information.

crashReporter.getLastCrashReport()

Returns CrashReport:

Returns the date and ID of the last crash report. If no crash reports have been sent or the crash reporter has not been started, null is returned.

crashReporter.getUploadedReports()

Returns CrashReport[]:

Returns all uploaded crash reports. Each report contains the date and uploaded ID.

crashReporter.getUploadToServer() Linux macOS

Returns Boolean - Whether reports should be submitted to the server. Set through the start method or setUploadToServer.

Note: This API can only be called from the main process.

crashReporter.setUploadToServer(uploadToServer) Linux macOS

• uploadToServer Boolean macOS - Whether reports should be submitted to the server.

This would normally be controlled by user preferences. This has no effect if called before start is called.

Note: This API can only be called from the main process.

crashReporter.addExtraParameter(key, value) macOS

• key String - Parameter key, must be less than 64 characters long.
• value String - Parameter value, must be less than 64 characters long.

Set an extra parameter to be sent with the crash report. The values specified here will be sent in addition to any values set via the extra option when start was called. This API is only available on macOS, if you need to add/update extra parameters on Linux and Windows after your first call to start you can call start again with the updated extra options.

crashReporter.removeExtraParameter(key) macOS

• key String - Parameter key, must be less than 64 characters long.

Remove a extra parameter from the current set of parameters so that it will not be sent with the crash report.

crashReporter.getParameters()

See all of the current parameters being passed to the crash reporter.

Crash Report Payload

The crash reporter will send the following data to the submitURL as a multipart/form-data POST:

• ver String - The version of Electron.
• platform String - e.g. 'win32'.
• process_type String - e.g. 'renderer'.
• guid String - e.g. '5e1286fc-da97-479e-918b-6bfb0c3d1c72'.
• _version String - The version in package.json.
• _productName String - The product name in the crashReporter options object.
• prod String - Name of the underlying product. In this case Electron.
• _companyName String - The company name in the crashReporter options object.
• upload_file_minidump File - The crash report in the format of minidump.
• All level one properties of the extra object in the crashReporter options object.

Debugging on Windows

If you experience crashes or issues in Electron that you believe are not caused by your JavaScript application, but instead by Electron itself, debugging can be a little bit tricky, especially for developers not used to native/C++ debugging. However, using Visual Studio, GitHub's hosted Electron Symbol Server, and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code.

Requirements

• A debug build of Electron: The easiest way is usually building it yourself, using the tools and prerequisites listed in the build instructions for Windows. While you can attach to and debug Electron as you can download it directly, you will find that it is heavily optimized, making debugging substantially more difficult: The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations.

• Visual Studio with C++ Tools: The free community editions of Visual Studio 2013 and Visual Studio 2015 both work. Once installed, configure Visual Studio to use GitHub's Electron Symbol server. It will enable Visual Studio to gain a better understanding of what happens inside Electron, making it easier to present variables in a human-readable format.

• ProcMon: The free SysInternals tool allows you to inspect a processes parameters, file handles, and registry operations.

Attaching to and Debugging Electron

To start a debugging session, open up PowerShell/CMD and execute your debug build of Electron, using the application to open as a parameter.

$ ./out/D/electron.exe ~/my-electron-app/

Setting Breakpoints

Then, open up Visual Studio. Electron is not built with Visual Studio and hence does not contain a project file - you can however open up the source code files "As File", meaning that Visual Studio will open them up by themselves. You can still set breakpoints - Visual Studio will automatically figure out that the source code matches the code running in the attached process and break accordingly.

Relevant code files can be found in ./atom/ as well as in Brightray, found in ./brightray/browser and ./brightray/common.

Attaching

You can attach the Visual Studio debugger to a running process on a local or remote computer. After the process is running, click Debug / Attach to Process (or press CTRL+ALT+P) to open the "Attach to Process" dialog box. You can use this capability to debug apps that are running on a local or remote computer, debug multiple processes simultaneously.

If Electron is running under a different user account, select the Show processes from all users check box. Notice that depending on how many BrowserWindows your app opened, you will see multiple processes. A typical one-window app will result in Visual Studio presenting you with two Electron.exe entries - one for the main process and one for the renderer process. Since the list only gives you names, there's currently no reliable way of figuring out which is which.

Which Process Should I Attach to?

Code executed within the main process (that is, code found in or eventually run by your main JavaScript file) as well as code called using the remote (require('electron').remote) will run inside the main process, while other code will execute inside its respective renderer process.

You can be attached to multiple programs when you are debugging, but only one program is active in the debugger at any time. You can set the active program in the Debug Location toolbar or the Processes window.

Using ProcMon to Observe a Process

While Visual Studio is fantastic for inspecting specific code paths, ProcMon's strength is really in observing everything your application is doing with the operating system - it captures File, Registry, Network, Process, and Profiling details of processes. It attempts to log all events occurring and can be quite overwhelming, but if you seek to understand what and how your application is doing to the operating system, it can be a valuable resource.

For an introduction to ProcMon's basic and advanced debugging features, go check out this video tutorial provided by Microsoft.

Class: Debugger

An alternate transport for Chrome's remote debugging protocol.

Process: Main

Chrome Developer Tools has a special binding available at JavaScript runtime that allows interacting with pages and instrumenting them.

const {BrowserWindow} = require('electron')
    let win = new BrowserWindow()
    
    try {
      win.webContents.debugger.attach('1.1')
    } catch (err) {
      console.log('Debugger attach failed : ', err)
    }
    
    win.webContents.debugger.on('detach', (event, reason) => {
      console.log('Debugger detached due to : ', reason)
    })
    
    win.webContents.debugger.on('message', (event, method, params) => {
      if (method === 'Network.requestWillBeSent') {
        if (params.request.url === 'https://www.github.com') {
          win.webContents.debugger.detach()
        }
      }
    })
    
    win.webContents.debugger.sendCommand('Network.enable')

Instance Methods

debugger.attach([protocolVersion])

• protocolVersion String (optional) - Requested debugging protocol version.

Attaches the debugger to the webContents.

debugger.isAttached()

Returns Boolean - Whether a debugger is attached to the webContents.

debugger.detach()

Detaches the debugger from the webContents.

debugger.sendCommand(method[, commandParams, callback])

• method String - Method name, should be one of the methods defined by the remote debugging protocol.
• commandParams Object (optional) - JSON object with request parameters.

• callback Function (optional) - Response

  • error Object - Error message indicating the failure of the command.
  • result Any - Response defined by the 'returns' attribute of the command description in the remote debugging protocol.

Send given command to the debugging target.

Instance Events

Event: 'detach'

• event Event
• reason String - Reason for detaching debugger.

Emitted when debugging session is terminated. This happens either when webContents is closed or devtools is invoked for the attached webContents.

Event: 'message'

• event Event
• method String - Method name.
• params Object - Event parameters defined by the 'parameters' attribute in the remote debugging protocol.

Emitted whenever debugging target issues instrumentation event.

Debugging on macOS

If you experience crashes or issues in Electron that you believe are not caused by your JavaScript application, but instead by Electron itself, debugging can be a little bit tricky, especially for developers not used to native/C++ debugging. However, using lldb, and the Electron source code, you can enable step-through debugging with breakpoints inside Electron's source code. You can also use XCode for debugging if you prefer a graphical interface.

Requirements

• A debug build of Electron: The easiest way is usually building it yourself, using the tools and prerequisites listed in the build instructions for macOS. While you can attach to and debug Electron as you can download it directly, you will find that it is heavily optimized, making debugging substantially more difficult: The debugger will not be able to show you the content of all variables and the execution path can seem strange because of inlining, tail calls, and other compiler optimizations.

• Xcode: In addition to Xcode, also install the Xcode command line tools. They include LLDB, the default debugger in Xcode on Mac OS X. It supports debugging C, Objective-C and C++ on the desktop and iOS devices and simulator.

Attaching to and Debugging Electron

To start a debugging session, open up Terminal and start lldb, passing a debug build of Electron as a parameter.

$ lldb ./out/D/Electron.app
    (lldb) target create "./out/D/Electron.app"
    Current executable set to './out/D/Electron.app' (x86_64).

Setting Breakpoints

LLDB is a powerful tool and supports multiple strategies for code inspection. For this basic introduction, let's assume that you're calling a command from JavaScript that isn't behaving correctly - so you'd like to break on that command's C++ counterpart inside the Electron source.

Relevant code files can be found in ./atom/ as well as in Brightray, found in ./brightray/browser and ./brightray/common.

Let's assume that you want to debug app.setName(), which is defined in browser.cc as Browser::SetName(). Set the breakpoint using the breakpoint command, specifying file and line to break on:

(lldb) breakpoint set --file browser.cc --line 117
    Breakpoint 1: where = Electron Framework`atom::Browser::SetName(std::__1::basic_string<char, std::__1::char_traits<char>, std::__1::allocator<char> > const&) + 20 at browser.cc:118, address = 0x000000000015fdb4

Then, start Electron:

(lldb) run

The app will immediately be paused, since Electron sets the app's name on launch:

(lldb) run
    Process 25244 launched: '/Users/fr/Code/electron/out/D/Electron.app/Contents/MacOS/Electron' (x86_64)
    Process 25244 stopped
    * thread #1: tid = 0x839a4c, 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name="Electron") + 20 at browser.cc:118, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
        frame #0: 0x0000000100162db4 Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name="Electron") + 20 at browser.cc:118
       115  }
       116
       117  void Browser::SetName(const std::string& name) {
    -> 118    name_override_ = name;
       119  }
       120
       121  int Browser::GetBadgeCount() {
    (lldb)

To show the arguments and local variables for the current frame, run frame variable (or fr v), which will show you that the app is currently setting the name to "Electron".

(lldb) frame variable
    (atom::Browser *) this = 0x0000000108b14f20
    (const string &) name = "Electron": {
        [...]
    }

To do a source level single step in the currently selected thread, execute step (or s). This would take you into name_override_.empty(). To proceed and do a step over, run next (or n).

(lldb) step
    Process 25244 stopped
    * thread #1: tid = 0x839a4c, 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name="Electron") + 44 at browser.cc:119, queue = 'com.apple.main-thread', stop reason = step in
        frame #0: 0x0000000100162dcc Electron Framework`atom::Browser::SetName(this=0x0000000108b14f20, name="Electron") + 44 at browser.cc:119
       116
       117  void Browser::SetName(const std::string& name) {
       118    name_override_ = name;
    -> 119  }
       120
       121  int Browser::GetBadgeCount() {
       122    return badge_count_;

To finish debugging at this point, run process continue. You can also continue until a certain line is hit in this thread (thread until 100). This command will run the thread in the current frame till it reaches line 100 in this frame or stops if it leaves the current frame.

Now, if you open up Electron's developer tools and call setName, you will once again hit the breakpoint.

Further Reading

LLDB is a powerful tool with a great documentation. To learn more about it, consider Apple's debugging documentation, for instance the LLDB Command Structure Reference or the introduction to Using LLDB as a Standalone Debugger.

You can also check out LLDB's fantastic manual and tutorial, which will explain more complex debugging scenarios.

Debugging with XCode

Build Debug Electron with Release libchromiumcontent

You can create a debug build of electron by following build instructions for macOS. The bootstrap process will download Release version of libchromiumcontent by default, so you will not be able to step through the chromium source.

Build Debug Electron with Debug libchromiumcontent

If you want to debug and step through libchromiumcontent, you will have to run the bootsrap script with the --build_debug_libcc argument.

$ cd electron
    $ ./script/bootstrap.py -v --build_debug_libcc

This can take a significant amount of time depending on build machine as it has to build all of the libchromium source.

Once, the lib is built, create a symlink to the built directory under download

ln -s vendor/libchromiumcontent/dist/main/shared_library vendor/download/libchromiumcontent/shared_library

Electron debug builds will use this shared library to link against.

$ ./script/build.py -c D --libcc

This will build debug electron with debug version of libchromiumcontent.

Generate xcode project for debugging sources (cannot build code from xcode)

Run the update script with the --xcode argument.

$ ./script/update.py --xcode

This will generate the electron.ninjs.xcworkspace. You will have to open this workspace to set breakpoints and inspect.

Debugging and breakpoints

Launch electron app after build. You can now open the xcode workspace created above and attach to the electron process through the Debug > Attach To Process > Electron debug menu. [Note: If you want to debug the renderer process, you need to attach to the Electron Helper as well.]

You can now set breakpoints in any of the indexed files. However, you will not be able to set breakpoints directly in the chromium source. To set break points in the chromium source, you can choose Debug > Breakpoints > Create Symbolic Breakpoint and set any function name as the symbol. This will set the breakpoint for all functions with that name, from all the classes if there are more than one. You can also do this step of setting break points prior to attaching the debugger, however, actual breakpoints for symbolic breakpoint functions may not show up until the debugger is attached to the app.

Debugging the Main Process

The DevTools in an Electron browser window can only debug JavaScript that's executed in that window (i.e. the web pages). To debug JavaScript that's executed in the main process you will need to use an external debugger and launch Electron with the --inspect or --inspect-brk switch.

Command Line Switches

Use one of the following command line switches to enable debugging of the main process:

--inspect=[port]

Electron will listen for V8 inspector protocol messages on the specified port, an external debugger will need to connect on this port. The default port is 5858.

electron --inspect=5858 your/app

--inspect-brk=[port]

Like --inspect but pauses execution on the first line of JavaScript.

External Debuggers

You will need to use a debugger that supports the V8 inspector protocol.

• Connect Chrome by visiting chrome://inspect and selecting to inspect the launched Electron app present there.
• Debugging the Main Process in VSCode

Debugging the Main Process in VSCode

1. Open an Electron project in VSCode.

$ git clone git@github.com:electron/electron-quick-start.git
    $ code electron-quick-start

2. Add a file .vscode/launch.json with the following configuration:

{
      "version": "0.2.0",
      "configurations": [
        {
          "name": "Debug Main Process",
          "type": "node",
          "request": "launch",
          "cwd": "${workspaceRoot}",
          "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron",
          "windows": {
            "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron.cmd"
          },
          "args" : ["."]
        }
      ]
    }

3. Debugging

Set some breakpoints in main.js, and start debugging in the Debug View. You should be able to hit the breakpoints.

Here is a pre-configured project that you can download and directly debug in VSCode: https://github.com/octref/vscode-electron-debug/tree/master/electron-quick-start

desktopCapturer

Access information about media sources that can be used to capture audio and video from the desktop using the [navigator.mediaDevices.getUserMedia] API.

Process: Renderer

The following example shows how to capture video from a desktop window whose title is Electron:

// In the renderer process.
    const {desktopCapturer} = require('electron')
    
    desktopCapturer.getSources({types: ['window', 'screen']}, (error, sources) => {
      if (error) throw error
      for (let i = 0; i < sources.length; ++i) {
        if (sources[i].name === 'Electron') {
          navigator.mediaDevices.getUserMedia({
            audio: false,
            video: {
              mandatory: {
                chromeMediaSource: 'desktop',
                chromeMediaSourceId: sources[i].id,
                minWidth: 1280,
                maxWidth: 1280,
                minHeight: 720,
                maxHeight: 720
              }
            }
          })
          .then((stream) => handleStream(stream))
          .catch((e) => handleError(e))
          return
        }
      }
    })
    
    function handleStream (stream) {
      const video = document.querySelector('video')
      video.srcObject = stream
      video.onloadedmetadata = (e) => video.play()
    }
    
    function handleError (e) {
      console.log(e)
    }

To capture video from a source provided by desktopCapturer the constraints passed to [navigator.mediaDevices.getUserMedia] must include chromeMediaSource: 'desktop', and audio: false.

To capture both audio and video from the entire desktop the constraints passed to [navigator.mediaDevices.getUserMedia] must include chromeMediaSource: 'desktop', for both audio and video, but should not include a chromeMediaSourceId constraint.

const constraints = {
      audio: {
        mandatory: {
          chromeMediaSource: 'desktop'
        }
      },
      video: {
        mandatory: {
          chromeMediaSource: 'desktop'
        }
      }
    }

Methods

The desktopCapturer module has the following methods:

desktopCapturer.getSources(options, callback)

• options Object

  • types String[] - An array of Strings that lists the types of desktop sources to be captured, available types are screen and window.
  • thumbnailSize Size (optional) - The size that the media source thumbnail should be scaled to. Default is 150 x 150.

• callback Function

  • error Error
  • sources DesktopCapturerSource[]

Starts gathering information about all available desktop media sources, and calls callback(error, sources) when finished.

sources is an array of DesktopCapturerSource objects, each DesktopCapturerSource represents a screen or an individual window that can be captured.

DesktopCapturerSource Object

• id String - The identifier of a window or screen that can be used as a chromeMediaSourceId constraint when calling [navigator.webkitGetUserMedia]. The format of the identifier will be window:XX or screen:XX, where XX is a random generated number.
• name String - A screen source will be named either Entire Screen or Screen <index>, while the name of a window source will match the window title.
• thumbnail NativeImage - A thumbnail image. Note: There is no guarantee that the size of the thumbnail is the same as the thumbnailSize specified in the options passed to desktopCapturer.getSources. The actual size depends on the scale of the screen or window.

Desktop Environment Integration

Different operating systems provide different features for integrating desktop applications into their desktop environments. For example, on Windows, applications can put shortcuts in the JumpList of task bar, and on Mac, applications can put a custom menu in the dock menu.

This guide explains how to integrate your application into those desktop environments with Electron APIs.

Notifications

See the Notifications documentation.

Recent Documents

See Recent Documents documentation.

Progress Bar

See the Progress Bar documentation.

Unity Launcher

See the Unity Launcher documentation.

Represented File for macOS Window

See the Represented File documentation.

Dragging files out of the window

See the Native File Drag & Drop documentation.

Developer Environment

Electron development is essentially Node.js development. To turn your operating system into an environment capable of building desktop apps with Electron, you will merely need Node.js, npm, a code editor of your choice, and a rudimentary understanding of your operating system's command line client.

Setting up macOS

Electron supports Mac OS X 10.9 (and all versions named macOS) and up. Apple does not allow running macOS in virtual machines unless the host computer is already an Apple computer, so if you find yourself in need of a Mac, consider using a cloud service that rents access to Macs (like MacInCloud or xcloud).

First, install a recent version of Node.js. We recommend that you install either the latest LTS or Current version available. Visit the Node.js download page and select the macOS Installer. While Homebrew is an offered option, but we recommend against it - many tools will be incompatible with the way Homebrew installs Node.js.

Once downloaded, execute the installer and let the installation wizard guide you through the installation.

Once installed, confirm that everything works as expected. Find the macOS Terminal application in your /Applications/Utilities folder (or by searching for the word Terminal in Spotlight). Open up Terminal or another command line client of your choice and confirm that both node and npm are available:

# This command should print the version of Node.js
    node -v
    
    # This command should print the version of npm
    npm -v

If both commands printed a version number, you are all set! Before you get started, you might want to install a code editor suited for JavaScript development.

Setting up Windows

Electron supports Windows 7 and later versions – attempting to develop Electron applications on earlier versions of Windows will not work. Microsoft provides free virtual machine images with Windows 10 for developers.

First, install a recent version of Node.js. We recommend that you install either the latest LTS or Current version available. Visit the Node.js download page and select the Windows Installer. Once downloaded, execute the installer and let the installation wizard guide you through the installation.

On the screen that allows you to configure the installation, make sure to select the Node.js runtime, npm package manager, and Add to PATH options.

Once installed, confirm that everything works as expected. Find the Windows PowerShell by opening the Start Menu and typing PowerShell. Open up PowerShell or another command line client of your choice and confirm that both node and npm are available:

# This command should print the version of Node.js
    node -v
    
    # This command should print the version of npm
    npm -v

If both commands printed a version number, you are all set! Before you get started, you might want to install a code editor suited for JavaScript development.

Setting up Linux

Generally speaking, Electron supports Ubuntu 12.04, Fedora 21, Debian 8 and later.

First, install a recent version of Node.js. Depending on your Linux distribution, the installation steps might differ. Assuming that you normally install software using a package manager like apt or pacman, use the official Node.js guidance on installing on Linux.

You're running Linux, so you likely already know how to operate a command line client. Open up your favorite client and confirm that both node and npm are available globally:

# This command should print the version of Node.js
    node -v
    
    # This command should print the version of npm
    npm -v

If both commands printed a version number, you are all set! Before you get started, you might want to install a code editor suited for JavaScript development.

A Good Editor

We might suggest two free popular editors built in Electron: GitHub's Atom and Microsoft's Visual Studio Code. Both of them have excellent JavaScript support.

If you are one of the many developers with a strong preference, know that virtually all code editors and IDEs these days support JavaScript.

DevTools Extension

Electron supports the Chrome DevTools Extension, which can be used to extend the ability of devtools for debugging popular web frameworks.

How to load a DevTools Extension

This document outlines the process for manually loading an extension. You may also try electron-devtools-installer, a third-party tool that downloads extensions directly from the Chrome WebStore.

To load an extension in Electron, you need to download it in Chrome browser, locate its filesystem path, and then load it by calling the BrowserWindow.addDevToolsExtension(extension) API.

Using the React Developer Tools as example:

1. Install it in Chrome browser.
2. Navigate to chrome://extensions, and find its extension ID, which is a hash string like fmkadmapgofadopljbjfkapdkoienihi.

3. Find out filesystem location used by Chrome for storing extensions:

   • on Windows it is %LOCALAPPDATA%\Google\Chrome\User Data\Default\Extensions;

   • on Linux it could be:

     • ~/.config/google-chrome/Default/Extensions/
     • ~/.config/google-chrome-beta/Default/Extensions/
     • ~/.config/google-chrome-canary/Default/Extensions/
     • ~/.config/chromium/Default/Extensions/
   • on macOS it is ~/Library/Application Support/Google/Chrome/Default/Extensions.
4. Pass the location of the extension to BrowserWindow.addDevToolsExtension API, for the React Developer Tools, it is something like: ~/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/0.15.0_0

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

The name of the extension is returned by BrowserWindow.addDevToolsExtension, and you can pass the name of the extension to the BrowserWindow.removeDevToolsExtension API to unload it.

Supported DevTools Extensions

Electron only supports a limited set of chrome.* APIs, so some extensions using unsupported chrome.* APIs for chrome extension features may not work. Following Devtools Extensions are tested and guaranteed to work in Electron:

• Ember Inspector
• React Developer Tools
• Backbone Debugger
• jQuery Debugger
• AngularJS Batarang
• Vue.js devtools
• Cerebral Debugger
• Redux DevTools Extension
• MobX Developer Tools

What should I do if a DevTools Extension is not working?

First please make sure the extension is still being maintained, some extensions can not even work for recent versions of Chrome browser, and we are not able to do anything for them.

Then file a bug at Electron's issues list, and describe which part of the extension is not working as expected.

dialog

Display native system dialogs for opening and saving files, alerting, etc.

Process: Main

An example of showing a dialog to select multiple files and directories:

const {dialog} = require('electron')
    console.log(dialog.showOpenDialog({properties: ['openFile', 'openDirectory', 'multiSelections']}))

The Dialog is opened from Electron's main thread. If you want to use the dialog object from a renderer process, remember to access it using the remote:

const {dialog} = require('electron').remote
    console.log(dialog)