refactor: move extension APIs to session.extensions (#45597)

refactor: move extensions to session.extensions
This commit is contained in:
Sam Maddock 2025-02-21 18:36:51 -05:00 committed by GitHub
parent a63f6143ea
commit e3f61b465d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
14 changed files with 508 additions and 205 deletions

124
docs/api/extensions-api.md Normal file
View file

@ -0,0 +1,124 @@
## Class: Extensions
> Load and interact with extensions.
Process: [Main](../glossary.md#main-process)<br />
_This class is not exported from the `'electron'` module. It is only available as a return value of other methods in the Electron API._
Instances of the `Extensions` class are accessed by using `extensions` property of
a `Session`.
### Instance Events
The following events are available on instances of `Extensions`:
#### Event: 'extension-loaded'
Returns:
* `event` Event
* `extension` [Extension](structures/extension.md)
Emitted after an extension is loaded. This occurs whenever an extension is
added to the "enabled" set of extensions. This includes:
* Extensions being loaded from `Extensions.loadExtension`.
* Extensions being reloaded:
* from a crash.
* if the extension requested it ([`chrome.runtime.reload()`](https://developer.chrome.com/extensions/runtime#method-reload)).
#### Event: 'extension-unloaded'
Returns:
* `event` Event
* `extension` [Extension](structures/extension.md)
Emitted after an extension is unloaded. This occurs when
`Session.removeExtension` is called.
#### Event: 'extension-ready'
Returns:
* `event` Event
* `extension` [Extension](structures/extension.md)
Emitted after an extension is loaded and all necessary browser state is
initialized to support the start of the extension's background page.
### Instance Methods
The following methods are available on instances of `Extensions`:
#### `extensions.loadExtension(path[, options])`
* `path` string - Path to a directory containing an unpacked Chrome extension
* `options` Object (optional)
* `allowFileAccess` boolean - Whether to allow the extension to read local files over `file://`
protocol and inject content scripts into `file://` pages. This is required e.g. for loading
devtools extensions on `file://` URLs. Defaults to false.
Returns `Promise<Extension>` - resolves when the extension is loaded.
This method will raise an exception if the extension could not be loaded. If
there are warnings when installing the extension (e.g. if the extension
requests an API that Electron does not support) then they will be logged to the
console.
Note that Electron does not support the full range of Chrome extensions APIs.
See [Supported Extensions APIs](extensions.md#supported-extensions-apis) for
more details on what is supported.
Note that in previous versions of Electron, extensions that were loaded would
be remembered for future runs of the application. This is no longer the case:
`loadExtension` must be called on every boot of your app if you want the
extension to be loaded.
```js
const { app, session } = require('electron')
const path = require('node:path')
app.whenReady().then(async () => {
await session.defaultSession.extensions.loadExtension(
path.join(__dirname, 'react-devtools'),
// allowFileAccess is required to load the devtools extension on file:// URLs.
{ allowFileAccess: true }
)
// Note that in order to use the React DevTools extension, you'll need to
// download and unzip a copy of the extension.
})
```
This API does not support loading packed (.crx) extensions.
**Note:** This API cannot be called before the `ready` event of the `app` module
is emitted.
**Note:** Loading extensions into in-memory (non-persistent) sessions is not
supported and will throw an error.
#### `extensions.removeExtension(extensionId)`
* `extensionId` string - ID of extension to remove
Unloads an extension.
**Note:** This API cannot be called before the `ready` event of the `app` module
is emitted.
#### `extensions.getExtension(extensionId)`
* `extensionId` string - ID of extension to query
Returns `Extension | null` - The loaded extension with the given ID.
**Note:** This API cannot be called before the `ready` event of the `app` module
is emitted.
#### `extensions.getAllExtensions()`
Returns `Extension[]` - A list of all loaded extensions.
**Note:** This API cannot be called before the `ready` event of the `app` module
is emitted.

View file

@ -14,7 +14,7 @@ but it also happens to support some other extension capabilities.
Electron only supports loading unpacked extensions (i.e., `.crx` files do not
work). Extensions are installed per-`session`. To load an extension, call
[`ses.loadExtension`](session.md#sesloadextensionpath-options):
[`ses.extensions.loadExtension`](extensions-api.md#extensionsloadextensionpath-options):
```js
const { session } = require('electron')

View file

@ -1485,7 +1485,7 @@ will not work on non-persistent (in-memory) sessions.
**Note:** On macOS and Windows 10 this word will be removed from the OS custom dictionary as well
#### `ses.loadExtension(path[, options])`
#### `ses.loadExtension(path[, options])` _Deprecated_
* `path` string - Path to a directory containing an unpacked Chrome extension
* `options` Object (optional)
@ -1532,7 +1532,9 @@ is emitted.
**Note:** Loading extensions into in-memory (non-persistent) sessions is not
supported and will throw an error.
#### `ses.removeExtension(extensionId)`
**Deprecated:** Use the new `ses.extensions.loadExtension` API.
#### `ses.removeExtension(extensionId)` _Deprecated_
* `extensionId` string - ID of extension to remove
@ -1541,7 +1543,9 @@ Unloads an extension.
**Note:** This API cannot be called before the `ready` event of the `app` module
is emitted.
#### `ses.getExtension(extensionId)`
**Deprecated:** Use the new `ses.extensions.removeExtension` API.
#### `ses.getExtension(extensionId)` _Deprecated_
* `extensionId` string - ID of extension to query
@ -1550,13 +1554,17 @@ Returns `Extension | null` - The loaded extension with the given ID.
**Note:** This API cannot be called before the `ready` event of the `app` module
is emitted.
#### `ses.getAllExtensions()`
**Deprecated:** Use the new `ses.extensions.getExtension` API.
#### `ses.getAllExtensions()` _Deprecated_
Returns `Extension[]` - A list of all loaded extensions.
**Note:** This API cannot be called before the `ready` event of the `app` module
is emitted.
**Deprecated:** Use the new `ses.extensions.getAllExtensions` API.
#### `ses.getStoragePath()`
Returns `string | null` - The absolute file system path where data for this
@ -1619,6 +1627,10 @@ session is persisted on disk. For in memory sessions this returns `null`.
A [`Cookies`](cookies.md) object for this session.
#### `ses.extensions` _Readonly_
A [`Extensions`](extensions-api.md) object for this session.
#### `ses.serviceWorkers` _Readonly_
A [`ServiceWorkers`](service-workers.md) object for this session.

View file

@ -14,6 +14,13 @@ This document uses the following convention to categorize breaking changes:
## Planned Breaking API Changes (36.0)
### Deprecated: Extension methods and events on `session`
`session.loadExtension`, `session.removeExtension`, `session.getExtension`,
`session.getAllExtensions`, 'extension-loaded' event, 'extension-unloaded'
event, and 'extension-ready' events have all moved to the new
`session.extensions` class.
### Removed: `systemPreferences.isAeroGlassEnabled()`
The `systemPreferences.isAeroGlassEnabled()` function has been removed without replacement.

View file

@ -96,9 +96,9 @@ of the extension is not working as expected.
[devtools-extension]: https://developer.chrome.com/extensions/devtools
[session]: ../api/session.md
[react-devtools]: https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi
[load-extension]: ../api/session.md#sesloadextensionpath-options
[load-extension]: ../api/extensions-api.md#extensionsloadextensionpath-options
[extension-structure]: ../api/structures/extension.md
[remove-extension]: ../api/session.md#sesremoveextensionextensionid
[remove-extension]: ../api/extensions-api.md#extensionsremoveextensionextensionid
[electron-devtools-installer]: https://github.com/MarshallOfSound/electron-devtools-installer
[supported-extension-apis]: ../api/extensions.md
[issue-tracker]: https://github.com/electron/electron/issues