Electron

https://www.electronjs.org/docs/latest
Admin
Electron is a framework for building cross-platform desktop applications using web technologies like...
Tokens:712,028
Snippets:5,994
Trust Score:9.9
Update:7 hours ago
Show doc for...
Tokens:
Raw
### Run the installed snap

Source: https://www.electronjs.org/docs/latest/tutorial/snapcraft

Launches the installed Electron snap application.

```sh
electron-packager-hello-world
```

--------------------------------

### app.startAppShimServer([options])

Source: https://www.electronjs.org/docs/latest/api/app

Starts accepting connections from app shims on macOS (experimental). An 'app-shim-connected' event is emitted for each shim that connects. Throws if the server cannot be started, for example because another copy of the app has already started a server with the same name.

```APIDOC
## app.startAppShimServer([options])

### Description
Starts accepting connections from app shims on macOS (experimental). An 'app-shim-connected' event is emitted for each shim that connects. Throws if the server cannot be started, for example because another copy of the app has already started a server with the same name.

### Method
app.startAppShimServer([options])

### Parameters
#### Optional Parameters
- **options** (Object) - Optional
  - **name** (string) - Optional - A name for this server, which lets several running copies of your app each have their own. It can only contain letters, digits, `.`, `-` and `_`, and must match the `ElectronAppShimServerName` of the shims that connect to it. Default is `appshim`.

### Notes
- This method can only be called after the app is ready.
- It is not available in Mac App Store builds.
```

--------------------------------

### Example package.json after setup

Source: https://www.electronjs.org/docs/latest/tutorial/tutorial-first-app

Shows the expected package.json after running npm init and installing Electron. The main field points to main.js and Electron is listed under devDependencies.

```json
{
  "name": "my-electron-app",
  "version": "1.0.0",
  "description": "Hello World!",
  "main": "main.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "Jane Doe",
  "license": "MIT",
  "devDependencies": {
    "electron": "23.1.3"
  }
}
```

--------------------------------

### Install electron-installer-snap

Source: https://www.electronjs.org/docs/latest/tutorial/snapcraft

Install the electron-installer-snap module as a development dependency using npm.

```sh
npm install --save-dev electron-installer-snap
```

--------------------------------

### Electron Quick Start main.js

Source: https://www.electronjs.org/docs/latest

Main process script for a basic Electron app. Creates a BrowserWindow with a preload script and loads index.html. Handles app lifecycle events: creates a window on ready, re-creates on activate (macOS), and quits when all windows are closed except on darwin.

```JavaScript
const { app, BrowserWindow } = require('electron/main')
const path = require('node:path')

function createWindow () {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  win.loadFile('index.html')
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow()
    }
  })
})

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit()
  }
})
```

--------------------------------

### Install Desktop App Converter with BaseImage

Source: https://www.electronjs.org/docs/latest/tutorial/windows-store-guide

Installs the Desktop App Converter, passing the Windows base image file. May prompt for a reboot; rerun after restart if needed.

```powershell
.\DesktopAppConverter.ps1 -Setup -BaseImage .\BaseImage-14316.wim
```

--------------------------------

### app.getApplicationInfoForProtocol(url)

Source: https://www.electronjs.org/docs/latest/api/app

Returns a promise that resolves with an object containing the application name, icon, and installation path of the default handler for the protocol of the given URL. The URL must include the protocol scheme.

```APIDOC
## [METHOD] app.getApplicationInfoForProtocol(url)

### Description
Returns a promise that resolves with an object containing the application name, icon, and installation path of the default handler for the protocol of the given URL. The URL must include the protocol scheme.

### Method
app.getApplicationInfoForProtocol

### Parameters
#### Path Parameters
- **url** (string) - Required - A URL with the protocol name to check, including `://` at a minimum (e.g., `https://`).

### Returns
- **Promise<Object>** - Resolves with an object containing:
  - **icon** (NativeImage) - The display icon of the app handling the protocol.
  - **path** (string) - Installation path of the app handling the protocol.
  - **name** (string) - Display name of the app handling the protocol.

```

--------------------------------

### app.startAccessingSecurityScopedResource(bookmarkData)

Source: https://www.electronjs.org/docs/latest/api/app

Starts accessing a security scoped resource, allowing Mac App Store packaged apps to reach outside their sandbox to access user-selected files. Returns a function that must be called when finished accessing the resource.

```APIDOC
## app.startAccessingSecurityScopedResource(bookmarkData)

### Description
Starts accessing a security scoped resource, allowing Mac App Store packaged apps to reach outside their sandbox to access user-selected files. Returns a function that must be called when finished accessing the resource.

### Method
startAccessingSecurityScopedResource

### Parameters
- **bookmarkData** (string) - Required - The base64 encoded security scoped bookmark data returned by `dialog.showOpenDialog` or `dialog.showSaveDialog`.

### Returns
- **Function** - A function that must be called once you have finished accessing the security scoped file.

### Example
```js
const { app, dialog } = require('electron')

const fs = require('node:fs')

let filepath
let bookmark

dialog.showOpenDialog(null, { securityScopedBookmarks: true }).then(({ filePaths, bookmarks }) => {
  filepath = filePaths[0]
  bookmark = bookmarks[0]
  fs.readFileSync(filepath)
})

// ... restart app ...

const stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(bookmark)
fs.readFileSync(filepath)
stopAccessingSecurityScopedResource()
```
```

--------------------------------

### main.js - Create BrowserWindow and load index.html

Source: https://www.electronjs.org/docs/latest/tutorial/keyboard-shortcuts

Sets up the Electron main process to create a BrowserWindow and load index.html. Required for the renderer keyboard shortcut example.

```javascript
// Modules to control application life and create native browser window
const { app, BrowserWindow } = require('electron/main')

function createWindow () {
  // Create the browser window.
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600
  })

  // and load the index.html of the app.
  mainWindow.loadFile('index.html')
}

// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(() => {
  createWindow()

  app.on('activate', function () {
    // On macOS it's common to re-create a window in the app when the
    // dock icon is clicked and there are no other windows open.
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

// Quit when all windows are closed, except on macOS. There, it's common
// for applications and their menu bar to stay active until the user quits
// explicitly with Cmd + Q.
app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})
```

--------------------------------

### Main process: handle select-serial-port and set permission handlers

Source: https://www.electronjs.org/docs/latest/tutorial/devices

Main process code for the Web Serial example. Listens for 'select-serial-port' to auto-select the first available port, sets permission check and device permission handlers for the file:// origin, and creates the BrowserWindow. Requires the renderer and HTML files to be present.

```js
const { app, BrowserWindow } = require('electron/main')

function createWindow () {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600
  })

  mainWindow.webContents.session.on('select-serial-port', (event, portList, webContents, callback) => {
    // Add listeners to handle ports being added or removed before the callback for `select-serial-port`
    // is called.
    mainWindow.webContents.session.on('serial-port-added', (event, port) => {
      console.log('serial-port-added FIRED WITH', port)
      // Optionally update portList to add the new port
    })

    mainWindow.webContents.session.on('serial-port-removed', (event, port) => {
      console.log('serial-port-removed FIRED WITH', port)
      // Optionally update portList to remove the port
    })

    event.preventDefault()
    if (portList && portList.length > 0) {
      callback(portList[0].portId)
    } else {
      callback('') // Could not find any matching devices
    }
  })

  mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'serial' && details.securityOrigin === 'file:///') {
      return true
    }

    return false
  })

  mainWindow.webContents.session.setDevicePermissionHandler((details) => {
    if (details.deviceType === 'serial' && details.origin === 'file://') {
      return true
    }

    return false
  })

  mainWindow.loadFile('index.html')

  mainWindow.webContents.openDevTools()
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})
```

--------------------------------

### Install and initialize @electron/build-tools

Source: https://www.electronjs.org/docs/latest/development/pull-requests

Install the build-tools package globally and run the init script to clone the project and point it to your fork. The --bootstrap testing flag initializes the project for testing. After completion, navigate to electron/src/electron where your fork is cloned.

```sh
# Install build-tools package globally:
npm install -g @electron/build-tools
# Run the init script where you want to clone the project and point it to your fork:
e init --fork my-org/electron --bootstrap testing
```

--------------------------------

### Markdown heading structure example (Quick Start)

Source: https://www.electronjs.org/docs/latest/development/style-guide

Shows the required heading hierarchy for Electron documentation pages: a single # title, ## chapters, and deeper sub-chapters with increasing # levels. The page title uses APA title case, while chapters use APA sentence case.

```markdown
# Quick Start

...

## Main process

...

## Renderer process

...

## Run your app

...

### Run as a distribution

...

### Manually downloaded Electron binary

...
```

--------------------------------

### Use cpp-linux addon in Electron main or renderer process

Source: https://www.electronjs.org/docs/latest/tutorial/native-code-and-electron-cpp-linux

Complete example showing how to import the addon, call helloWorld(), set up event listeners for GTK GUI interactions, and launch the native GTK3 window with helloGui(). The helloWorld() call returns a greeting from C++, and the event listeners trigger when users interact with the GTK3 GUI.

```js
// In your Electron main process or renderer process
import cppLinux from 'cpp-linux'

// Test the basic functionality
console.log(cppLinux.helloWorld('Hi!'))
// Output: "Hello from C++! You said: Hi!"

// Set up event listeners for GTK GUI interactions
cppLinux.on('todoAdded', (todo) => {
  console.log('New todo added:', todo)
  // todo: { id: "uuid-string", text: "Todo text", date: Date object }
})

cppLinux.on('todoUpdated', (todo) => {
  console.log('Todo updated:', todo)
})

cppLinux.on('todoDeleted', (todo) => {
  console.log('Todo deleted:', todo)
})

// Launch the native GTK GUI
cppLinux.helloGui()
```

--------------------------------

### Initialize GTK and run main loop in hello_gui()

Source: https://www.electronjs.org/docs/latest/tutorial/native-code-and-electron-cpp-linux

Checks if the GTK thread is already running, initializes GTK with gtk_init_check, creates a new main context and loop, then starts a background thread that creates a GtkApplication and connects its activate signal. Prints error messages if GTK is already running or fails to initialize.

```cpp
  void hello_gui()
  {
    if (g_gtk_thread != nullptr)
    {
      g_print("GTK application is already running.\n");
      return;
    }

    if (!gtk_init_check(0, nullptr))
    {
      g_print("Failed to initialize GTK.\n");
      return;
    }

    g_gtk_main_context = g_main_context_new();
    g_main_loop = g_main_loop_new(g_gtk_main_context, FALSE);

    g_gtk_thread = new std::thread([]()
                                   {
        GtkApplication* app = gtk_application_new("com.example.todo", G_APPLICATION_NON_UNIQUE);
        g_signal_connect(app, "activate", G_CALLBACK(activate_handler), nullptr);
```

--------------------------------

### Install and run electron-chromedriver (npm)

Source: https://www.electronjs.org/docs/latest/tutorial/automated-testing

Install the electron-chromedriver package and start the ChromeDriver server. The server runs on port 9515 and only allows local connections.

```sh
npm install --save-dev electron-chromedriver
./node_modules/.bin/chromedriver
Starting ChromeDriver (v2.10.291558) on port 9515
Only local connections are allowed.
```

--------------------------------

### Install and run electron-chromedriver (Yarn)

Source: https://www.electronjs.org/docs/latest/tutorial/automated-testing

Install the electron-chromedriver package using Yarn and start the ChromeDriver server. The server runs on port 9515 and only allows local connections.

```sh
yarn add --dev electron-chromedriver
./node_modules/.bin/chromedriver
Starting ChromeDriver (v2.10.291558) on port 9515
Only local connections are allowed.
```

--------------------------------

### Run the app with npm start

Source: https://www.electronjs.org/docs/latest/tutorial/tutorial-first-app

Executes the Electron app using npm. The terminal should print 'Hello from Electron 👋'. This is the npm variant of the start command.

```sh
npm run start
```

--------------------------------

### main.js: Set up USB device permission handlers

Source: https://www.electronjs.org/docs/latest/tutorial/devices

Main process code that creates a BrowserWindow and configures session handlers for USB device selection, permission checks, device permission grants, and protected class filtering. It listens for 'select-usb-device' events and uses setPermissionCheckHandler, setDevicePermissionHandler, and setUSBProtectedClassesHandler to manage USB access.

```JavaScript
const { app, BrowserWindow } = require('electron/main')

function createWindow () {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600
  })

  let grantedDeviceThroughPermHandler

  mainWindow.webContents.session.on('select-usb-device', (event, details, callback) => {
    // Add events to handle devices being added or removed before the callback on
    // `select-usb-device` is called.
    mainWindow.webContents.session.on('usb-device-added', (event, device) => {
      console.log('usb-device-added FIRED WITH', device)
      // Optionally update details.deviceList
    })

    mainWindow.webContents.session.on('usb-device-removed', (event, device) => {
      console.log('usb-device-removed FIRED WITH', device)
      // Optionally update details.deviceList
    })

    event.preventDefault()
    if (details.deviceList && details.deviceList.length > 0) {
      const deviceToReturn = details.deviceList.find((device) => {
        return !grantedDeviceThroughPermHandler || (device.deviceId !== grantedDeviceThroughPermHandler.deviceId)
      })
      if (deviceToReturn) {
        callback(deviceToReturn.deviceId)
      } else {
        callback()
      }
    }
  })

  mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'usb' && details.securityOrigin === 'file:///') {
      return true
    }
  })

  mainWindow.webContents.session.setDevicePermissionHandler((details) => {
    if (details.deviceType === 'usb' && details.origin === 'file://') {
      if (!grantedDeviceThroughPermHandler) {
        grantedDeviceThroughPermHandler = details.device
        return true
      } else {
        return false
      }
    }
  })

  mainWindow.webContents.session.setUSBProtectedClassesHandler((details) => {
    return details.protectedClasses.filter((usbClass) => {
      // Exclude classes except for audio classes
      return usbClass.indexOf('audio') === -1
    })
  })

  mainWindow.loadFile('index.html')
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})
```

--------------------------------

### Install snap with --dangerous flag

Source: https://www.electronjs.org/docs/latest/tutorial/snapcraft

Installs the locally built snap package. The --dangerous flag is required because the snap is not signed by the store.

```sh
sudo snap install electron-packager-hello-world_0.1_amd64.snap --dangerous
```

--------------------------------

### Example .desktop file with custom actions

Source: https://www.electronjs.org/docs/latest/tutorial/linux-desktop-actions

Shows how to define custom launcher actions in a .desktop file using Actions, Name, and Exec properties. The desktop executes the Exec command when the user clicks the shortcut menu item.

```plaintext
Actions=PlayPause;Next;Previous

[Desktop Action PlayPause]
Name=Play-Pause
Exec=audacious -t

[Desktop Action Next]
Name=Next
Exec=audacious -f

[Desktop Action Previous]
Name=Previous
Exec=audacious -r
```

--------------------------------

### Install electron-windows-store CLI

Source: https://www.electronjs.org/docs/latest/tutorial/windows-store-guide

Install the electron-windows-store command-line tool globally via npm. Requires Windows 10 with Anniversary Update, the Windows 10 SDK, and at least Node 4.

```sh
npm install -g electron-windows-store
```

--------------------------------

### Initialize npm project

Source: https://www.electronjs.org/docs/latest/tutorial/tutorial-first-app

Creates the project folder and runs npm init to scaffold the package.json. The entry point should be set to main.js.

```sh
mkdir my-electron-app && cd my-electron-app
npm init
```

--------------------------------

### Event: 'browser-window-focus'

Source: https://www.electronjs.org/docs/latest/api/app

Emitted when a browserWindow gets focused.

```APIDOC
## Event: 'browser-window-focus'

### Description
Emitted when a browserWindow gets focused.

### Returns
- `event` Event
- `window` BrowserWindow
```

--------------------------------

### Run the app with yarn start

Source: https://www.electronjs.org/docs/latest/tutorial/tutorial-first-app

Executes the Electron app using Yarn. The terminal should print 'Hello from Electron 👋'. This is the Yarn variant of the start command.

```sh
yarn run start
```

--------------------------------

### Event: 'browser-window-blur'

Source: https://www.electronjs.org/docs/latest/api/app

Emitted when a browserWindow gets blurred.

```APIDOC
## Event: 'browser-window-blur'

### Description
Emitted when a browserWindow gets blurred.

### Returns
- `event` Event
- `window` BrowserWindow
```

--------------------------------

### GTK UI setup with GtkBuilder and signal connections

Source: https://www.electronjs.org/docs/latest/tutorial/native-code-and-electron-cpp-linux

Sets up a GTK application UI by loading an inline XML layout with gtk_builder_add_from_string, retrieving widgets, and connecting signals. The XML defines a window with an entry, calendar, add button, and a list box. Requires a GtkBuilder instance and an application object; the builder is passed to the add button callback.

```cpp
    gtk_builder_add_from_string(builder,
                                "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
                                "<interface>"
                                "  <object class=\"GtkWindow\" id=\"window\">"
                                "    <property name=\"title\">Todo List</property>"
                                "    <property name=\"default-width\">400</property>"
                                "    <property name=\"default-height\">500</property>"
                                "    <child>"
                                "      <object class=\"GtkBox\">"
                                "        <property name=\"visible\">true</property>"
                                "        <property name=\"orientation\">vertical</property>"
                                "        <property name=\"spacing\">6</property>"
                                "        <property name=\"margin\">12</property>"
                                "        <child>"
                                "          <object class=\"GtkBox\">"
                                "            <property name=\"visible\">true</property>"
                                "            <property name=\"spacing\">6</property>"
                                "            <child>"
                                "              <object class=\"GtkEntry\" id=\"todo_entry\">"
                                "                <property name=\"visible\">true</property>"
                                "                <property name=\"hexpand\">true</property>"
                                "                <property name=\"placeholder-text\">Enter todo item...</property>"
                                "              </object>"
                                "            </child>"
                                "            <child>"
                                "              <object class=\"GtkCalendar\" id=\"todo_calendar\">"
                                "                <property name=\"visible\">true</property>"
                                "              </object>"
                                "            </child>"
                                "            <child>"
                                "              <object class=\"GtkButton\" id=\"add_button\">"
                                "                <property name=\"visible\">true</property>"
                                "                <property name=\"label\">Add</property>"
                                "              </object>"
                                "            </child>"
                                "          </object>"
                                "        </child>"
                                "        <child>"
                                "          <object class=\"GtkScrolledWindow\">"
                                "            <property name=\"visible\">true</property>"
                                "            <property name=\"vexpand\">true</property>"
                                "            <child>"
                                "              <object class=\"GtkListBox\" id=\"todo_list\">"
                                "                <property name=\"visible\">true</property>"
                                "                <property name=\"selection-mode\">single</property>"
                                "              </object>"
                                "            </child>"
                                "          </object>"
                                "        </child>"
                                "      </object>"
                                "    </child>"
                                "  </object>"
                                "</interface>",
                                -1, nullptr);

    auto *window = GTK_WINDOW(gtk_builder_get_object(builder, "window"));
    auto *button = GTK_BUTTON(gtk_builder_get_object(builder, "add_button"));
    auto *list = GTK_LIST_BOX(gtk_builder_get_object(builder, "todo_list"));

    gtk_window_set_application(window, app);

    g_signal_connect(button, "clicked", G_CALLBACK(on_add_clicked), builder);
    g_signal_connect(list, "row-activated", G_CALLBACK(on_row_activated), nullptr);

    gtk_widget_show_all(GTK_WIDGET(window));
  }
```

--------------------------------

### Electron Quick Start preload.js

Source: https://www.electronjs.org/docs/latest

Preload script that runs in the renderer before the page loads. Listens for DOMContentLoaded and replaces text in elements with the versions of Chrome, Node, and Electron from process.versions.

```JavaScript
window.addEventListener('DOMContentLoaded', () => {
  const replaceText = (selector, text) => {
    const element = document.getElementById(selector)
    if (element) element.innerText = text
  }

  for (const type of ['chrome', 'node', 'electron']) {
    replaceText(`${type}-version`, process.versions[type])
  }
})
```

--------------------------------

### Install WebdriverIO test runner with Yarn

Source: https://www.electronjs.org/docs/latest/tutorial/automated-testing

Alternative to npm for starting the WebdriverIO configuration wizard. It installs necessary packages and generates a wdio.conf.js file. Select 'Desktop Testing - of Electron Applications' when prompted.

```sh
yarn create wdio@latest ./
```

--------------------------------

### main.js: Create window, build context menu, and handle IPC

Source: https://www.electronjs.org/docs/latest/tutorial/context-menu

Sets up the main process: creates a BrowserWindow with a preload script, builds a context menu with copy/cut/paste/selectall roles, and listens for the 'context-menu' IPC message to pop up the menu on the sender's window. Requires the preload.js and index.html files shown in the same example.

```JavaScript
// Modules to control application life and create native browser window
const { app, BrowserWindow, ipcMain, Menu } = require('electron/main')
const path = require('node:path')

function createWindow () {
  const mainWindow = new BrowserWindow({
    webPreferences: {
      preload: path.join(__dirname, 'preload.js')
    }
  })

  mainWindow.loadFile('index.html')
  const menu = Menu.buildFromTemplate([
    { role: 'copy' },
    { role: 'cut' },
    { role: 'paste' },
    { role: 'selectall' }
  ])

  ipcMain.on('context-menu', (event) => {
    menu.popup({
      window: BrowserWindow.fromWebContents(event.sender)
    })
  })
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})
```

```JavaScript
const { ipcRenderer } = require('electron/renderer')

document.addEventListener('DOMContentLoaded', () => {
  const textarea = document.getElementById('editable')
  textarea.addEventListener('contextmenu', (event) => {
    event.preventDefault()
    ipcRenderer.send('context-menu')
  })
})
```

```HTML
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>Context Menu Demo</title>
  </head>
  <body>
    <h1>Context Menu Demo</h1>
    <textarea id="editable"></textarea>
  </body>
</html>
```

--------------------------------

### ses.netLog

Source: https://www.electronjs.org/docs/latest/api/session

A readonly property that returns a `NetLog` object for this session. Includes an example of starting and stopping network logging.

```APIDOC
## Property: ses.netLog

### Description
A `NetLog` object for this session.

### Type
`NetLog`

### Readonly
Yes

### Example
```js
const { app, session } = require('electron')

app.whenReady().then(async () => {
  const netLog = session.fromPartition('some-partition').netLog
  netLog.startLogging('/path/to/net-log')
  // After some network events
  const path = await netLog.stopLogging()
  console.log('Net-logs written to', path)
})
```
```

--------------------------------

### Create project directory structure

Source: https://www.electronjs.org/docs/latest/tutorial/native-code-and-electron

Shell commands to create the required directories for the addon project: src for source files, include for headers, and js for the JavaScript wrapper.

```sh
mkdir src
mkdir include
mkdir js
```

--------------------------------

### Install WebdriverIO test runner with npm

Source: https://www.electronjs.org/docs/latest/tutorial/automated-testing

Run this command in your project root to start the WebdriverIO configuration wizard. It installs necessary packages and generates a wdio.conf.js file. Select 'Desktop Testing - of Electron Applications' when prompted.

```sh
npm init wdio@latest ./
```

--------------------------------

### Starter code for custom title bar tutorial

Source: https://www.electronjs.org/docs/latest/tutorial/custom-title-bar

Basic Electron main process script that creates a BrowserWindow loading https://example.com. Use this as the starting point for the custom title bar tutorial.

```javascript
const { app, BrowserWindow } = require('electron')

function createWindow () {
  const win = new BrowserWindow({})
  win.loadURL('https://example.com')
}

app.whenReady().then(() => {
  createWindow()
})
```

--------------------------------

### Electron Quick Start index.html

Source: https://www.electronjs.org/docs/latest

HTML page for the Electron app. Displays a heading and a paragraph that shows the Node.js, Chromium, and Electron versions. Includes a Content-Security-Policy meta tag allowing 'self' and 'unsafe-inline' scripts.

```HTML
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Hello World!</title>
    <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
</head>
<body>
    <h1>Hello World!</h1>
    <p>
        We are using Node.js <span id="node-version"></span>,
        Chromium <span id="chrome-version"></span>,
        and Electron <span id="electron-version"></span>.
    </p>
</body>
</html>
```

--------------------------------

### Using the addon in Electron main process

Source: https://www.electronjs.org/docs/latest/tutorial/native-code-and-electron

Imports the addon as a module and calls helloWorld in the main process, which has Node.js enabled.

```js
// In your main process
const myAddon = require('my-native-addon')

console.log(myAddon.helloWorld('Electron'))
```

--------------------------------

### Set-ExecutionPolicy bypass

Source: https://www.electronjs.org/docs/latest/tutorial/windows-store-guide

Run from an elevated PowerShell to allow execution of the Desktop App Converter scripts. Required before installing the converter.

```powershell
Set-ExecutionPolicy bypass
```

--------------------------------

### Example cache directory structure

Source: https://www.electronjs.org/docs/latest/tutorial/installation

Cached zip files are stored in subdirectories named by @electron/get. This shows a typical cache layout.

```sh
├── 523ee27feac8b931299c79e78b7ca4f365aa3f7069fff666cae93c7fb9ff2fee
│   └── electron-v15.3.1-darwin-x64.zip
```

--------------------------------

### In-App Purchase main process example

Source: https://www.electronjs.org/docs/latest/tutorial/in-app-purchases

Shows how to listen for transactions, check purchase state, retrieve products, and purchase a product. Replace product IDs with your own and listen to 'transactions-updated' as early as possible.

```javascript
// Main process
const { inAppPurchase } = require('electron')

const PRODUCT_IDS = ['id1', 'id2']

// Listen for transactions as soon as possible.
inAppPurchase.on('transactions-updated', (event, transactions) => {
  if (!Array.isArray(transactions)) {
    return
  }

  // Check each transaction.
  for (const transaction of transactions) {
    const payment = transaction.payment

    switch (transaction.transactionState) {
      case 'purchasing':
        console.log(`Purchasing ${payment.productIdentifier}...`)
        break

      case 'purchased': {
        console.log(`${payment.productIdentifier} purchased.`)

        // Get the receipt url.
        const receiptURL = inAppPurchase.getReceiptURL()

        console.log(`Receipt URL: ${receiptURL}`)

        // Submit the receipt file to the server and check if it is valid.
        // @see https://developer.apple.com/library/content/releasenotes/General/ValidateAppStoreReceipt/Chapters/ValidateRemotely.html
        // ...
        // If the receipt is valid, the product is purchased
        // ...

        // Finish the transaction.
        inAppPurchase.finishTransactionByDate(transaction.transactionDate)

        break
      }

      case 'failed':
        console.log(`Failed to purchase ${payment.productIdentifier}.`)

        // Finish the transaction.
        inAppPurchase.finishTransactionByDate(transaction.transactionDate)

        break
      case 'restored':
        console.log(`The purchase of ${payment.productIdentifier} has been restored.`)

        break
      case 'deferred':
        console.log(`The purchase of ${payment.productIdentifier} has been deferred.`)

        break
      default:
        break
    }
  }
})

// Check if the user is allowed to make in-app purchase.
if (!inAppPurchase.canMakePayments()) {
  console.log('The user is not allowed to make in-app purchase.')
}

// Retrieve and display the product descriptions.
inAppPurchase.getProducts(PRODUCT_IDS).then((products) => {
  // Check the parameters.
  if (!Array.isArray(products) || products.length <= 0) {
    console.log('Unable to retrieve the product information.')
    return
  }

  // Display the name and price of each product.
  for (const product of products) {
    console.log(`The price of ${product.localizedTitle} is ${product.formattedPrice}.`)
  }

  // Ask the user which product they want to purchase.
  const selectedProduct = products[0]
  const selectedQuantity = 1

  // Purchase the selected product.
  inAppPurchase.purchaseProduct(selectedProduct.productIdentifier, selectedQuantity).then((isProductValid) => {
    if (!isProductValid) {
      console.log('The product is not valid.')
      return
    }

    console.log('The payment has been added to the payment queue.')
  })
})
```

--------------------------------

### Retrieve all history entries with getAllEntries

Source: https://www.electronjs.org/docs/latest/tutorial/navigation-history

Get the full browsing history as an array of entries and log each entry's title and URL.

```javascript
const entries = navigationHistory.getAllEntries()

entries.forEach((entry) => {
  console.log(`${entry.title}: ${entry.url}`)
})
```

--------------------------------

### Generate MSI installer with electron-wix-msi and windowsSign

Source: https://www.electronjs.org/docs/latest/tutorial/code-signing

Use electron-wix-msi's MSICreator to generate an MSI installer with the same windowsSign options as @electron/packager. The example shows the three-step workflow: instantiate the creator, create a .wxs template file (optionally signing support binaries), then compile to a .msi file.

```javascript
import { MSICreator } from 'electron-wix-msi'

// Step 1: Instantiate the MSICreator
const msiCreator = new MSICreator({
  appDirectory: '/path/to/built/app',
  description: 'My amazing Kitten simulator',
  exe: 'kittens',
  name: 'Kittens',
  manufacturer: 'Kitten Technologies',
  version: '1.1.2',
  outputDirectory: '/path/to/output/folder',
  windowsSign: {
    signWithParams: '--my=custom --parameters',
    // If signtool.exe does not work for you, customize!
    signToolPath: 'C:\\Path\\To\\my-custom-tool.exe'
  }
})

// Step 2: Create a .wxs template file
const supportBinaries = await msiCreator.create()

// 🆕 Step 2a: optionally sign support binaries if you
// sign your binaries as part of your packaging script
for (const binary of supportBinaries) {
  // Binaries are the new stub executable and optionally
  // the Squirrel auto updater.
  await signFile(binary)
}

// Step 3: Compile the template to a .msi file
await msiCreator.compile()
```

--------------------------------

### Main process: select-hid-device and permission handlers

Source: https://www.electronjs.org/docs/latest/tutorial/devices

Main process code that handles HID device selection via the 'select-hid-device' event and sets permission check and device permission handlers. Includes event listeners for device added/removed and window lifecycle.

```javascript
const { app, BrowserWindow } = require('electron/main')

function createWindow () {
  const mainWindow = new BrowserWindow({
    width: 800,
    height: 600
  })

  mainWindow.webContents.session.on('select-hid-device', (event, details, callback) => {
    // Add events to handle devices being added or removed before the callback on
    // `select-hid-device` is called.
    mainWindow.webContents.session.on('hid-device-added', (event, device) => {
      console.log('hid-device-added FIRED WITH', device)
      // Optionally update details.deviceList
    })

    mainWindow.webContents.session.on('hid-device-removed', (event, device) => {
      console.log('hid-device-removed FIRED WITH', device)
      // Optionally update details.deviceList
    })

    event.preventDefault()
    if (details.deviceList && details.deviceList.length > 0) {
      callback(details.deviceList[0].deviceId)
    }
  })

  mainWindow.webContents.session.setPermissionCheckHandler((webContents, permission, requestingOrigin, details) => {
    if (permission === 'hid' && details.securityOrigin === 'file:///') {
      return true
    }
  })

  mainWindow.webContents.session.setDevicePermissionHandler((details) => {
    if (details.deviceType === 'hid' && details.origin === 'file://') {
      return true
    }
  })

  mainWindow.loadFile('index.html')
}

app.whenReady().then(() => {
  createWindow()

  app.on('activate', function () {
    if (BrowserWindow.getAllWindows().length === 0) createWindow()
  })
})

app.on('window-all-closed', function () {
  if (process.platform !== 'darwin') app.quit()
})
```

--------------------------------

### Event: 'before-quit'

Source: https://www.electronjs.org/docs/latest/api/app

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

```APIDOC
## Event: 'before-quit'

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

### Event
`before-quit`

### Returns
- `event` Event

### Notes
- If application quit was initiated by `autoUpdater.quitAndInstall()`, then `before-quit` is emitted _after_ emitting `close` event on all windows and closing them.
- 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.
```

--------------------------------

### Initialize Electron build with e init

Source: https://www.electronjs.org/docs/latest/development/build-instructions-gn

Bootstraps a local checkout of Electron using `e init`. The `--bootstrap` flag runs `e sync` and `e build`. The `--root` option specifies where Electron's source and build files will reside; it defaults to `$PWD/electron`. You may be asked to run `e d rbe login` during the initial sync phase.

```sh
# The 'Hello, World!' of build-tools: get and build `main`
# Choose the directory where Electron's source and build files will reside.
# You can specify any path you like; this command defaults to `$PWD/electron`.
# If you're going to use multiple branches, you may want something like:
# `--root=~/electron/branch` (e.g. `~/electron-gn/main`)
e init --root=~/electron --bootstrap testing
```

--------------------------------

### Initialize Yarn project

Source: https://www.electronjs.org/docs/latest/tutorial/tutorial-first-app

Creates the project folder and runs yarn init to scaffold the package.json. The entry point should be set to main.js.

```sh
mkdir my-electron-app && cd my-electron-app
yarn init
```

--------------------------------

### Use system clang with clang_base_path

Source: https://www.electronjs.org/docs/latest/development/build-instructions-linux

Specify the `clang_base_path` argument in GN args to build with a system-installed `clang` instead of the prebuilt binaries. The example assumes `clang` is installed under `/usr/local/bin/clang`.

```sh
$ gn gen out/Testing --args='import("//electron/build/args/testing.gn") clang_base_path = "/usr/local/bin"'
```

--------------------------------

### API History block for ipcRenderer change

Source: https://www.electronjs.org/docs/latest/development/style-guide

Second part of the multi-API change example. Place the same API History block under the top-level header for each affected API, here ipcRenderer.

```markdown
# ipcRenderer

<!--
```YAML history
changes:
  - pr-url: https://github.com/electron/electron/pull/40330
    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
```
-->

Process: [Renderer](../glossary.md#renderer-process)
```

--------------------------------

### Packaged Electron application output structure

Source: https://www.electronjs.org/docs/latest/tutorial/snapcraft

Example output structure after packaging the Electron application with @electron/packager. The dist/app-linux-x64 directory contains the application files and dependencies.

```plaintext
.
└── dist
    └── app-linux-x64
        ├── LICENSE
        ├── LICENSES.chromium.html
        ├── content_shell.pak
        ├── app
        ├── icudtl.dat
        ├── libgcrypt.so.11
        ├── libnode.so
        ├── locales
        ├── resources
        ├── v8_context_snapshot.bin
        └── version
```

--------------------------------

### GTK Application Setup: init_gtk_app and activate_handler

Source: https://www.electronjs.org/docs/latest/tutorial/native-code-and-electron-cpp-linux

Sets up the GTK application in native C++ code running alongside Electron. The init_gtk_app function runs the GTK application loop on its own thread (g_gtk_thread) and quits the main loop when done. The activate_handler creates a GtkBuilder and registers application actions (edit, delete) using GActionEntry.

```cpp
  static gboolean init_gtk_app(gpointer user_data)
  {
    auto *app = static_cast<GtkApplication *>(user_data);
    g_application_run(G_APPLICATION(app), 0, nullptr);
    g_object_unref(app);
    if (g_main_loop)
    {
      g_main_loop_quit(g_main_loop);
    }
    return G_SOURCE_REMOVE;
  }

  static void activate_handler(GtkApplication *app, gpointer user_data)
  {
    auto *builder = gtk_builder_new();

    const GActionEntry app_actions[] = {
        {"edit", edit_action, nullptr, nullptr, nullptr, {0, 0, 0}},
        {"delete", delete_action, nullptr, nullptr, nullptr, {0, 0, 0}}};
    g_action_map_add_action_entries(G_ACTION_MAP(app), app_actions,
                                    G_N_ELEMENTS(app_actions), builder);

```

--------------------------------

### Start Electron REPL with --interactive flag

Source: https://www.electronjs.org/docs/latest/tutorial/repl

Launches an interactive Node.js REPL in the Electron main process. Requires electron installed as a local project dependency. Not available on Windows (see electron/electron#5776).

```sh
./node_modules/.bin/electron --interactive
```

--------------------------------

### HTML page for Web Serial example

Source: https://www.electronjs.org/docs/latest/tutorial/devices

HTML file for the Web Serial example. Contains a button to trigger the serial request and a placeholder for the device name. Loads the renderer script.

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>Web Serial API</title>
  <body>
    <h1>Web Serial API</h1>

    <button id="clickme">Test Web Serial API</button>

    <p>Matching Arduino Uno device: <strong id="device-name""></strong></p>

    <script src="./renderer.js"></script>
  </body>
</html>
```

--------------------------------

### Deprecated: systemPreferences.{get,set}AppLevelAppearance and appLevelAppearance

Source: https://www.electronjs.org/docs/latest/breaking-changes

The systemPreferences.getAppLevelAppearance, setAppLevelAppearance methods and the appLevelAppearance property are deprecated; use the nativeTheme module instead. The example shows replacements for each deprecated call.

```javascript
// Deprecated
systemPreferences.getAppLevelAppearance()
// Replace with
nativeTheme.shouldUseDarkColors

// Deprecated
systemPreferences.appLevelAppearance
// Replace with
nativeTheme.shouldUseDarkColors

// Deprecated
systemPreferences.setAppLevelAppearance('dark')
// Replace with
nativeTheme.themeSource = 'dark'
```

--------------------------------

### Example basic response from app.getGPUInfo('basic')

Source: https://www.electronjs.org/docs/latest/api/app

Shows the structure of the object returned when calling app.getGPUInfo('basic'). The response includes auxAttributes, gpuDevice, machineModelName, and machineModelVersion. Use 'basic' when only vendorId or deviceId is needed.

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

--------------------------------

### Breaking change entry in breaking-changes.md

Source: https://www.electronjs.org/docs/latest/development/api-history-migration-guide

Shows the deprecated API entry found in docs/breaking-changes.md and the corresponding API documentation in docs/api/browser-window.md. Used as the starting point for adding API History blocks.

```markdown
<!-- docs/breaking-changes.md -->
### Deprecated: `BrowserWindow.getTrafficLightPosition()`

`BrowserWindow.getTrafficLightPosition()` has been deprecated, the
`BrowserWindow.getWindowButtonPosition()` API should be used instead
which returns `null` instead of `{ x: 0, y: 0 }` when there is no custom
position.

<!-- docs/api/browser-window.md  -->
#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_

Returns `Point` - The custom position for the traffic light buttons in
frameless window, `{ x: 0, y: 0 }` will be returned when there is no custom
position.
```

--------------------------------

### index.html for WebHID example

Source: https://www.electronjs.org/docs/latest/tutorial/devices

HTML page with a button to test WebHID and placeholders for granted devices. Includes a Content Security Policy.

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
    <title>WebHID API</title>
  </head>
  <body>
    <h1>WebHID API</h1>

    <button id="clickme">Test WebHID</button>

    <h3>HID devices automatically granted access via <i>setDevicePermissionHandler</i></h3>
    <div id="granted-devices"></div>

    <h3>HID devices automatically granted access via <i>select-hid-device</i></h3>
    <div id="granted-devices2"></div>

    <script src="./renderer.js"></script>
  </body>
</html>
```
Tokens:
Raw