|
1 | | -# webpack-extension-reloader |
2 | | -A upgrade from webpack-chrome-extension-reloader, now on all browsers |
| 1 | +# Webpack Extension Reloader |
| 2 | +A Webpack plugin to enable hot reloading while developing browser extensions. |
| 3 | + |
| 4 | +<div align="center"> |
| 5 | + <a href="https://github.com/webpack/webpack"> |
| 6 | + <img width="200" height="200" src="https://webpack.js.org/assets/icon-square-big.svg"> |
| 7 | + </a> |
| 8 | + <br> |
| 9 | + <br> |
| 10 | +</div> |
| 11 | + |
| 12 | +[](https://badge.fury.io/js/webpack-extension-reloader) |
| 13 | +[](https://travis-ci.org/rubenspgcavalcante/webpack-extension-reloader) |
| 14 | +[](https://www.npmjs.com/package/webpack-extension-reloader) |
| 15 | +[](https://www.codacy.com/app/rubenspgcavalcante/webpack-extension-reloader?utm_source=github.com&utm_medium=referral&utm_content=rubenspgcavalcante/webpack-extension-reloader&utm_campaign=Badge_Grade) |
| 16 | + |
| 17 | +## Installing |
| 18 | + |
| 19 | +npm |
| 20 | +``` |
| 21 | +npm install webpack-extension-reloader --save-dev |
| 22 | +``` |
| 23 | + |
| 24 | +yarn |
| 25 | +``` |
| 26 | +yarn add webpack-extension-reloader --dev |
| 27 | +``` |
| 28 | + |
| 29 | +## Solution for ... |
| 30 | +Have your ever being annoyed while developing a browser extension, and being unable to use |
| 31 | +webpack-hot-server because it's not a web app but a browser extension? |
| 32 | + |
| 33 | +Well, now you can do hot reloading! |
| 34 | + |
| 35 | + |
| 36 | + |
| 37 | +## What it does? |
| 38 | +Basically something similar to what the webpack hot reload middleware does. When you change the code and the webpack |
| 39 | +trigger and finish the compilation, your extension is notified and then reloaded using the [standard browser runtime API](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions). |
| 40 | +Check out [Hot reloading extensions using Webpack](https://medium.com/front-end-hacking/hot-reloading-extensions-using-webpack-cdfa0e4d5a08) for more background. |
| 41 | + |
| 42 | +## How to use |
| 43 | +### Using as a plugin |
| 44 | +Add `webpack-extension-reloader` to the plugins section of your webpack configuration file. |
| 45 | +```js |
| 46 | +const ExtensionReloader = require('webpack-extension-reloader'); |
| 47 | + |
| 48 | +plugins: [ |
| 49 | + new ExtensionReloader() |
| 50 | +] |
| 51 | +``` |
| 52 | + |
| 53 | +You can also set some options (the following are the default ones): |
| 54 | +```js |
| 55 | +// webpack.dev.js |
| 56 | +module.exports = { |
| 57 | + mode: "development", // The plugin is activated only if mode is set to development |
| 58 | + watch: true, |
| 59 | + entry: { |
| 60 | + 'content-script': './my-content-script.js', |
| 61 | + background: './my-background-script.js' |
| 62 | + }, |
| 63 | + //... |
| 64 | + plugins: [ |
| 65 | + new ExtensionReloader({ |
| 66 | + port: 9090, // Which port use to create the server |
| 67 | + reloadPage: true, // Force the reload of the page also |
| 68 | + entries: { // The entries used for the content/background scripts |
| 69 | + contentScript: 'content-script', // Use the entry names, not the file name or the path |
| 70 | + background: 'background' // *REQUIRED |
| 71 | + } |
| 72 | + }) |
| 73 | + ] |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +And then just run your application with Webpack in watch mode: |
| 78 | +```bash |
| 79 | +NODE_ENV=development webpack --config myconfig.js --mode=development --watch |
| 80 | +``` |
| 81 | + |
| 82 | +**Important**: You need to set `--mode=development` to activate the plugin (only if you didn't set on the webpack.config.js already) then you need to run with `--watch`, as the plugin will be able to sign the extension only if webpack triggers the rebuild (again, only if you didn't set on webpack.config). |
| 83 | + |
| 84 | +### Multiple Content Script support |
| 85 | +If you use more than one content script in your extension, like: |
| 86 | +```js |
| 87 | +entry: { |
| 88 | + 'my-first-content-script': './my-first-content-script.js', |
| 89 | + 'my-second-content-script': './my-second-content-script.js', |
| 90 | + // and so on ... |
| 91 | + background: './my-background-script.js' |
| 92 | +} |
| 93 | +``` |
| 94 | + |
| 95 | +You can use the `entries.contentScript` options as an array: |
| 96 | +```js |
| 97 | +plugins: [ |
| 98 | + new ExtensionReloader({ |
| 99 | + entries: { |
| 100 | + contentScript: ['my-first-content-script', 'my-second-content-script', /* and so on ... */], |
| 101 | + background: 'background' |
| 102 | + } |
| 103 | + }) |
| 104 | +] |
| 105 | +``` |
| 106 | + |
| 107 | +### CLI |
| 108 | +If you don't want all the plugin setup, you can just use the client that comes with the package. |
| 109 | +You can use by installing the package globally, or directly using `npx` after installing locally the plugin: |
| 110 | + |
| 111 | +```bash |
| 112 | +npx webpack-extension-reloader |
| 113 | +``` |
| 114 | +If you run directly, it will use the default configurations, but if you want to customize |
| 115 | +you can call it with the following options: |
| 116 | +```bash |
| 117 | +npx webpack-extension-reloader --config wb.config.js --port 9080 --no-page-reload --content-script my-content.js --background bg.js |
| 118 | +``` |
| 119 | +If you have **multiple** content scripts, just use comma (with no spaces) while passing the option |
| 120 | +```bash |
| 121 | +npx webpack-extension-reloader --content-script my-first-content.js,my-second-content.js,my-third-content.js |
| 122 | +``` |
| 123 | + |
| 124 | +### Client options |
| 125 | + |
| 126 | +| name | default | description | |
| 127 | +| ---------------- | ----------------- | ----------------------------------------------------------------- | |
| 128 | +| --help | | Shows this help | |
| 129 | +| --config | webpack.config.js | The webpack configuration file path | |
| 130 | +| --port | 9090 | The port to run the server | |
| 131 | +| --content-script | content-script | The **entry/entries** name(s) for the content script(s) | |
| 132 | +| --background | background | The **entry** name for the background script | |
| 133 | +| --no-page-reload | | Disable the auto reloading of all **pages** which runs the plugin | |
| 134 | + |
| 135 | +Every time webpack triggers a compilation, the extension reloader are going to do the hot reload :) |
| 136 | +**Note:** the plugin only works on **development** mode, so don't forget to set the NODE_ENV before run the command above |
| 137 | + |
| 138 | +### Contributing |
| 139 | +Please before opening any **issue** or **pull request** check the [contribution guide](/.github/CONTRIBUTING.MD). |
| 140 | + |
| 141 | +### Building and Testing |
| 142 | +Inside this repository have an example plugin, so you can test and see it working |
| 143 | +After cloning the repository, run: |
| 144 | +``` |
| 145 | +yarn build |
| 146 | +``` |
| 147 | + |
| 148 | + And then run: |
| 149 | + ``` |
| 150 | + yarn sample |
| 151 | + ``` |
| 152 | + |
| 153 | + This will make the webpack run in watch mode for the sample plugin source and output the built files on the "dist" |
| 154 | + directory. |
| 155 | + Load the extension **(the files in "sample/dist" directory)** using the "load unpacked extension", open a |
| 156 | + new tab in any site and open the developer panel on it. Watch the dev. tools console tab, and do some changes on |
| 157 | + the background or content script. Voila! |
| 158 | + |
| 159 | +**Note:** |
| 160 | +The hot reload requires a browser supporting the [Standard Browser Extension API](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions). |
| 161 | + |
| 162 | +You must have both background and content scripts for this plugin to work, and they must be specified in separate `entry` chunks |
| 163 | +in your webpack config. |
| 164 | + |
| 165 | +The reloading script will be injected only on the main entries chunks (in background and content script). Any other |
| 166 | +chunks will be ignored. |
| 167 | + |
| 168 | +### License |
| 169 | +This project is under the [MIT LICENSE](http://opensource.org/licenses/MIT) |
0 commit comments