mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

docs: update devtools extension tutorial (#26326)

Browse source 
* docs: update devtools extension tutorial

* Update docs/tutorial/devtools-extension.md

Co-authored-by: Jeremy Rose <nornagon@nornagon.net>

* update

Co-authored-by: Jeremy Rose <nornagon@nornagon.net>
This commit is contained in:
Erick Zhao 2021-01-10 21:43:08 -08:00 • committed by GitHub
parent 088f2e625f
commit c6769af29b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 63 additions and 41 deletions
Download patch file Download diff file Expand all files Collapse all files

98
docs/tutorial/devtools-extension.md
View file

@ -1,25 +1,28 @@
# DevTools Extension # DevTools Extension
Electron supports the [Chrome DevTools Extension][devtools-extension], which can Electron supports [Chrome DevTools extensions][devtools-extension], which can
be used to extend the ability of devtools for debugging popular web frameworks. be used to extend the ability of Chrome's developer tools for debugging
popular web frameworks.
## How to load a DevTools Extension ## Loading a DevTools extension with tooling
This document outlines the process for manually loading an extension. The easiest way to load a DevTools extension is to use third-party tooling to automate the
You may also try process for you. [electron-devtools-installer][electron-devtools-installer] is a popular
[electron-devtools-installer](https://github.com/GPMDP/electron-devtools-installer), NPM package that does just that.
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, ## Manually loading a DevTools extension
locate its filesystem path, and then load it by calling the
`BrowserWindow.addDevToolsExtension(extension)` API.
Using the [React Developer Tools][react-devtools] as example: If you don't want to use the tooling approach, you can also do all of the necessary
operations by hand. To load an extension in Electron, you need to download it via Chrome,
locate its filesystem path, and then load it into your [Session][session] by calling the
[`ses.loadExtension`] API.
1. Install it in Chrome browser. Using the [React Developer Tools][react-devtools] as an example:
1. Install the extension in Google Chrome.
1. Navigate to `chrome://extensions`, and find its extension ID, which is a hash 1. Navigate to `chrome://extensions`, and find its extension ID, which is a hash
string like `fmkadmapgofadopljbjfkapdkoienihi`. string like `fmkadmapgofadopljbjfkapdkoienihi`.
1. Find out filesystem location used by Chrome for storing extensions: 1. Find out the filesystem location used by Chrome for storing extensions:
* on Windows it is `%LOCALAPPDATA%\Google\Chrome\User Data\Default\Extensions`; * on Windows it is `%LOCALAPPDATA%\Google\Chrome\User Data\Default\Extensions`;
* on Linux it could be: * on Linux it could be:
* `~/.config/google-chrome/Default/Extensions/` * `~/.config/google-chrome/Default/Extensions/`
@ -27,37 +30,48 @@ Using the [React Developer Tools][react-devtools] as example:
* `~/.config/google-chrome-canary/Default/Extensions/` * `~/.config/google-chrome-canary/Default/Extensions/`
* `~/.config/chromium/Default/Extensions/` * `~/.config/chromium/Default/Extensions/`
* on macOS it is `~/Library/Application Support/Google/Chrome/Default/Extensions`. * on macOS it is `~/Library/Application Support/Google/Chrome/Default/Extensions`.
1. Pass the location of the extension to `BrowserWindow.addDevToolsExtension` 1. Pass the location of the extension to the [`ses.loadExtension`][load-extension]
API, for the React Developer Tools, it is something like: API. For React Developer Tools `v4.9.0`, it looks something like:
```javascript ```javascript
const { app, session } = require('electron')
const path = require('path') const path = require('path')
const os = require('os') const os = require('os')
BrowserWindow.addDevToolsExtension( // on macOS
path.join(os.homedir(), '/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.3.0_0') const reactDevToolsPath = path.join(
os.homedir(),
'/Library/Application Support/Google/Chrome/Default/Extensions/fmkadmapgofadopljbjfkapdkoienihi/4.9.0_0'
) )
app.whenReady().then(async () => {
await session.defaultSession.loadExtension(reactDevToolsPath)
})
``` ```
**Note:** The `BrowserWindow.addDevToolsExtension` API cannot be called before the **Notes:**
ready event of the app module is emitted.
The extension will be remembered so you only need to call this API once per * `loadExtension` returns a Promise with an [Extension object][extension-structure],
extension. If you try to add an extension that has already been loaded, this method which contains metadata about the extension that was loaded. This promise needs to
will not return and instead log a warning to the console. resolve (e.g. with an `await` expression) before loading a page. Otherwise, the
extension won't be guaranteed to load.
* `loadExtension` cannot be called before the `ready` event of the `app` module
is emitted, nor can it be called on in-memory (non-persistent) sessions.
* `loadExtension` must be called on every boot of your app if you want the
extension to be loaded.
### How to remove a DevTools Extension ### Removing a DevTools extension
You can pass the name of the extension to the `BrowserWindow.removeDevToolsExtension` You can pass the extension's ID to the [`ses.removeExtension`][remove-extension] API to
API to remove it. The name of the extension is returned by remove it from your Session. Loaded extensions are not persisted between
`BrowserWindow.addDevToolsExtension` and you can get the names of all installed app launches.
DevTools Extensions using the `BrowserWindow.getDevToolsExtensions` API.
## Supported DevTools Extensions ## DevTools extension support
Electron only supports a limited set of `chrome.*` APIs, so some extensions Electron only supports
using unsupported `chrome.*` APIs for chrome extension features may not work. [a limited set of `chrome.*` APIs][supported-extension-apis],
Following Devtools Extensions are tested and guaranteed to work in Electron: so extensions using unsupported `chrome.*` APIs under the hood may not work.
The following Devtools extensions have been tested to work in Electron:
* [Ember Inspector](https://chrome.google.com/webstore/detail/ember-inspector/bmdblncegkenkacieihfhpjfppoconhi) * [Ember Inspector](https://chrome.google.com/webstore/detail/ember-inspector/bmdblncegkenkacieihfhpjfppoconhi)
* [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) * [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi)
@ -69,14 +83,22 @@ Following Devtools Extensions are tested and guaranteed to work in Electron:
* [Redux DevTools Extension](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd) * [Redux DevTools Extension](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd)
* [MobX Developer Tools](https://chrome.google.com/webstore/detail/mobx-developer-tools/pfgnfdagidkfgccljigdamigbcnndkod) * [MobX Developer Tools](https://chrome.google.com/webstore/detail/mobx-developer-tools/pfgnfdagidkfgccljigdamigbcnndkod)
### What should I do if a DevTools Extension is not working? ### What should I do if a DevTools extension is not working?
First please make sure the extension is still being maintained, some extensions First, please make sure the extension is still being maintained and is compatible
can not even work for recent versions of Chrome browser, and we are not able to with the latest version of Google Chrome. We cannot provide additional support for
do anything for them. unsupported extensions.
Then file a bug at Electron's issues list, and describe which part of the If the extension works on Chrome but not on Electron, file a bug in Electron's
extension is not working as expected. [issue tracker][issue-tracker] and describe which part
of the extension is not working as expected.
[devtools-extension]: https://developer.chrome.com/extensions/devtools [devtools-extension]: https://developer.chrome.com/extensions/devtools
[session]: ../api/session.md
[react-devtools]: https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi [react-devtools]: https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi
[load-extension]: ../api/session.md#sesloadextensionpath
[extension-structure]: ../api/structures/extension.md
[remove-extension]: ../api/session.md#sesremoveextensionextensionid
[electron-devtools-installer]: https://github.com/MarshallOfSound/electron-devtools-installer
[supported-extension-apis]: ../api/extensions.md
[issue-tracker]: https://github.com/electron/electron/issues