mirrors/electron
0
0 Fork 0
mirror of https://github.com/electron/electron.git synced 2026-10-28 11:44:46 +08:00
Code Activity
Files
main
electron/docs/api/extensions.md
T
Sam MaddockandClaude bc658b2924 fix: extension code drift (#55155) 
* fix: report tab ids to extension webRequest and declarativeNetRequest

ElectronExtensionsBrowserClient did not override
GetTabAndWindowIdForWebContents, so the default of -1 reached every
caller: chrome.webRequest reported details.tabId as -1 and
declarativeNetRequest rules with a tabIds condition never matched.
Return the WebContents id, the same id chrome.tabs uses.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: keep extension service workers registered when clearing storage

Chrome's embedder refuses to delete or web-update the registration of
an extension's background service worker and only lets the manifest's
worker script register at the extension's root scope. Electron used
the content defaults, so session.clearStorageData() deleted the
registration and the extension stopped receiving events until it was
reloaded.

Override MayDeleteServiceWorkerRegistration,
ShouldTryToUpdateServiceWorkerRegistration and AllowServiceWorker to
match.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: crash in chrome.cookies.getAllCookieStores

The cookies API now lives in //extensions, so extensions with the
"cookies" permission can call it in Electron. Core code dereferences
ExtensionsAPIClient::GetCookiesApiDelegate(), which Electron did not
provide, crashing the browser process, and the CookiesAPI factory that
dispatches cookies.onChanged is only built by embedders.

Provide a delegate that lists the session as its own cookie store and
build the factory.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: restore the management permission feature

The "management" entry was dropped from Electron's permission features
when the file was resynced with Chrome's in #44653. The management API
feature depends on it, so a manifest requesting the permission lost it
and chrome.management.getAll, get, onEnabled and onDisabled were
unavailable.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: localize messages in extension stylesheets

Chromium substitutes __MSG_*__ placeholders in extension CSS with a
renderer URL loader throttle that only Chrome's throttle provider
installs. Electron had no provider, so placeholders such as
__MSG_@@extension_id__ were left as literal text. Install the throttle
from RendererClientBase.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: let WebSocket activity keep extension service workers alive

Chrome forwards ShouldNotifyServiceWorkerOnWebSocketActivity to the
extensions dispatcher so traffic on a WebSocket resets an extension
service worker's idle timer. Electron did not, so a worker holding an
open socket was still stopped after 30 seconds.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: keep sandboxed extension frames out of the extension process map

Chrome isolates only manifest-sandboxed extension pages (and sandboxed
about:srcdoc and data: documents) in a separate process and leaves that
process out of the extension ProcessMap, so it cannot be granted
extension API access. Electron isolated every sandboxed extension frame
and recorded each of those processes as a privileged extension process.

Override ShouldAllowCrossProcessSandboxedFrameForPrecursor and skip
sandboxed principals in SiteInstanceGotProcessAndSite to match.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: support navigator.clipboard in extension service workers

Chromium exposes navigator.clipboard to extension service workers, but
every piece that enables it lives in Chrome's embedder. Register
chrome-extension as an extension scheme with Blink, pass
--extension-process to extension renderers and turn the runtime feature
on there, and answer IsClipboardAllowedForServiceWorker and
AllowWorkerWriteToClipboard in the browser. Writes still require the
clipboardWrite permission.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: run the extension service worker script on disk after a restart

A service worker registration outlives the app, and Chromium trusts a
stored registration as current while the extension's version is
unchanged. Electron loads unpacked extensions on every launch, so an
extension whose files changed without a version bump kept running the
worker script from the launch that first registered it.

Unregister a worker left by a previous launch before adding the
extension so it is registered again from the files being loaded.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: persist extension alarms and dynamic content scripts

ElectronExtensionSystem returned null for the state, rules and dynamic
user scripts stores, so chrome.alarms and content scripts registered
with persistAcrossSessions were forgotten when the app quit. Create the
three StateStores as Chrome's extension system does.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: report webRequest proxying to the service worker loader

content asks HasWebRequestAPIProxy before starting a service worker
AutoPreload request, because a preload that is raced and dropped is
reported to webRequest listeners as a failed request. Answer for both
Electron's webRequest module and extensions that proxy requests.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: use the app name in extension warnings

ElectronExtensionsClient::GetProductName still returned "app_shell",
the name of the Chromium embedder it was copied from, which extension
warning messages interpolate.

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: remove stale extension feature entries

These keys name permissions, manifest keys and API functions that
Chromium has removed or that Electron's schemas do not define, so they
matched nothing.

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: update extension support notes

The background key is supported for Manifest V3 service workers too,
and chrome.management needs the management permission.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
2026-10-23 13:41:53 -04:00

5.9 KiB
Raw Permalink Blame History

Chrome Extension Support

Electron supports a subset of the Chrome Extensions API, primarily to support DevTools extensions and Chromium-internal extensions, but it also happens to support some other extension capabilities.

Note

Electron does not support arbitrary Chrome extensions from the store, and it is a non-goal of the Electron project to be perfectly compatible with Chrome's implementation of Extensions.

Loading extensions

Electron only supports loading unpacked extensions (i.e., .crx files do not work). Extensions are installed per-session. To load an extension, call ses.extensions.loadExtension:

const { session } = require('electron')

session.defaultSession.loadExtension('path/to/unpacked/extension').then(({ id }) => {
  // ...
})

Loaded extensions will not be automatically remembered across exits; if you do not call loadExtension when the app runs, the extension will not be loaded.

Note that loading extensions is only supported in persistent sessions. Attempting to load an extension into an in-memory session will throw an error.

See the session documentation for more information about loading, unloading, and querying active extensions.

Supported Extensions APIs

We support the following extensions APIs, with some caveats. Other APIs may additionally be supported, but support for any APIs not listed here is provisional and may be removed.

Supported Manifest Keys

  • name
  • version
  • author
  • permissions
  • content_scripts
  • default_locale
  • devtools_page
  • short_name
  • host_permissions (Manifest V3)
  • manifest_version
  • background
  • minimum_chrome_version

See Manifest file format for more information about the purpose of each possible key.

chrome.devtools.inspectedWindow

All features of this API are supported.

See official documentation for more information.

chrome.devtools.network

All features of this API are supported.

See official documentation for more information.

chrome.devtools.panels

All features of this API are supported.

See official documentation for more information.

chrome.extension

The following properties of chrome.extension are supported:

  • chrome.extension.lastError

The following methods of chrome.extension are supported:

  • chrome.extension.getURL
  • chrome.extension.getBackgroundPage

See official documentation for more information.

chrome.management

The following methods of chrome.management are supported:

  • chrome.management.getAll
  • chrome.management.get
  • chrome.management.getSelf
  • chrome.management.getPermissionWarningsById
  • chrome.management.getPermissionWarningsByManifest

The following events of chrome.management are supported:

  • chrome.management.onEnabled
  • chrome.management.onDisabled

Apart from chrome.management.getSelf and chrome.management.getPermissionWarningsByManifest, these require the management permission.

See official documentation for more information.

chrome.runtime

The following properties of chrome.runtime are supported:

  • chrome.runtime.lastError
  • chrome.runtime.id

The following methods of chrome.runtime are supported:

  • chrome.runtime.getBackgroundPage
  • chrome.runtime.getManifest
  • chrome.runtime.getPlatformInfo
  • chrome.runtime.getURL
  • chrome.runtime.connect
  • chrome.runtime.sendMessage
  • chrome.runtime.reload

The following events of chrome.runtime are supported:

  • chrome.runtime.onStartup
  • chrome.runtime.onInstalled
  • chrome.runtime.onSuspend
  • chrome.runtime.onSuspendCanceled
  • chrome.runtime.onConnect
  • chrome.runtime.onMessage

See official documentation for more information.

chrome.scripting

All features of this API are supported.

See official documentation for more information.

chrome.storage

The following methods of chrome.storage are supported:

  • chrome.storage.local
  • chrome.storage.sync (partial support)
    • stored on disk next to chrome.storage.local in a separate storage area and subject to Chrome's sync quotas; data is not synced across devices, matching Chrome with sync disabled.

chrome.storage.managed is not supported.

See official documentation for more information.

chrome.tabs

The following methods of chrome.tabs are supported:

  • chrome.tabs.sendMessage
  • chrome.tabs.reload
  • chrome.tabs.executeScript
  • chrome.tabs.query (partial support)
    • supported properties: url, title, audible, active, muted.
  • chrome.tabs.update (partial support)
    • supported properties: url, muted.

Note

In Chrome, passing -1 as a tab ID signifies the "currently active tab". Since Electron has no such concept, passing -1 as a tab ID is not supported and will raise an error.

See official documentation for more information.

chrome.webRequest

All features of this API are supported.

Note

Electron's webRequest module takes precedence over chrome.webRequest if there are conflicting handlers.

See official documentation for more information.

View Git Blame Copy Permalink