From d1e56f416ce75059d2bb80d3ea7138d32d091c86 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Sun, 29 May 2016 15:19:41 +0900 Subject: [PATCH] Update the docs on using DevTools extension --- docs/tutorial/devtools-extension.md | 84 +++++++++++++---------------- 1 file changed, 37 insertions(+), 47 deletions(-) diff --git a/docs/tutorial/devtools-extension.md b/docs/tutorial/devtools-extension.md index 1791c0459207..f004b1f31127 100644 --- a/docs/tutorial/devtools-extension.md +++ b/docs/tutorial/devtools-extension.md @@ -1,62 +1,52 @@ # DevTools Extension -To make debugging easier, Electron has basic support for the -[Chrome DevTools Extension][devtools-extension]. +Electron supports the [Chrome DevTools Extension][devtools-extension], which can +be used to extend the ability of devtools for debugging popular web frameworks. -For most DevTools extensions you can simply download the source code and use -the `BrowserWindow.addDevToolsExtension` API to load them. The loaded extensions -will be remembered so you don't need to call the API every time when creating -a window. +## How to load a DevTools Extension -** NOTE: React DevTools does not work, follow the issue here https://github.com/electron/electron/issues/915 ** +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. -For example, to use the [React DevTools Extension](https://github.com/facebook/react-devtools) -, first you need to download its source code: +Using the [React Developer Tools][react-devtools] as example: -```bash -$ cd /some-directory -$ git clone --recursive https://github.com/facebook/react-devtools.git -``` +1. Install it in Chrome browser. +1. Navigate to `chrome://extensions`, and find its extension ID, which is a hash + string like `fmkadmapgofadopljbjfkapdkoienihi`. +1. Find out filesystem location used by Chrome for storing extensions: + * on Windows it is `%LOCALAPPDATA%\Google\Chrome\User Data\Default\Extensions`; + * on Linux it is `~/.config/google-chrome/Default/Extensions/`; + * on OS X it is `~/Library/Application Support/Google/Chrome/Default/Extensions`. +1. 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.14.10_0` -Follow the instructions in [`react-devtools/shells/chrome/Readme.md`](https://github.com/facebook/react-devtools/blob/master/shells/chrome/Readme.md) to build the extension. +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. -Then you can load the extension in Electron by opening DevTools in any window, -and running the following code in the DevTools console: +## Supported DevTools Extensions -```javascript -const BrowserWindow = require('electron').remote.BrowserWindow; -BrowserWindow.addDevToolsExtension('/some-directory/react-devtools/shells/chrome'); -``` +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: -To unload the extension, you can call the `BrowserWindow.removeDevToolsExtension` -API with its name and it will not load the next time you open the DevTools: +* [Ember Inspector](https://chrome.google.com/webstore/detail/ember-inspector/bmdblncegkenkacieihfhpjfppoconhi) +* [React Developer Tools](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) +* [Backbone Debugger](https://chrome.google.com/webstore/detail/backbone-debugger/bhljhndlimiafopmmhjlgfpnnchjjbhd) +* [jQuery Debugger](https://chrome.google.com/webstore/detail/jquery-debugger/dbhhnnnpaeobfddmlalhnehgclcmjimi) +* [AngularJS Batarang](https://chrome.google.com/webstore/detail/angularjs-batarang/ighdmehidhipcmcojjgiloacoafjmpfk) +* [Vue.js devtools](https://chrome.google.com/webstore/detail/vuejs-devtools/nhdogjmejiglipccpnnnanhbledajbpd) -```javascript -BrowserWindow.removeDevToolsExtension('React Developer Tools'); -``` +### What should I do if a DevTools Extension is not working? -## Format of DevTools Extension +Fist 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. -Ideally all DevTools extensions written for the Chrome browser can be loaded by -Electron, but they have to be in a plain directory. For those packaged with -`crx` extensions, there is no way for Electron to load them unless you find a -way to extract them into a directory. - -## Background Pages - -Currently Electron doesn't support the background pages feature in Chrome -extensions, so some DevTools extensions that rely on this feature may -not work in Electron. - -## `chrome.*` APIs - -Some Chrome extensions may use `chrome.*` APIs for features and while there has -been some effort to implement those APIs in Electron, not all have been -implemented. - -Given that not all `chrome.*` APIs are implemented if the DevTools extension is -using APIs other than `chrome.devtools.*`, the extension is very likely not to -work. You can report failing extensions in the issue tracker so that we can add -support for those APIs. +Then file a bug at Electron's issues list, and describe which part of the +extension is not working as expected. [devtools-extension]: https://developer.chrome.com/extensions/devtools +[react-devtools]: https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi