docs: add security page and remove minimum version notices

nklayman · nklayman · commit 7f922c0e4e16 · 2020-05-30T19:55:20.000-07:00
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -1,7 +1,7 @@
 module.exports = {
   title: 'Vue CLI Plugin Electron Builder',
   description:
-  'A Vue CLI 3 plugin for Electron with no required configuration.',
+    'A Vue CLI 3/4 plugin for Electron with no required configuration.',
   base: '/vue-cli-plugin-electron-builder/',
   ga: 'UA-134189455-2',
   head: [
@@ -35,6 +35,7 @@ module.exports = {
         'guide',
         'configuration',
         'recipes',
+        'security',
         'testingAndDebugging',
         'commonIssues'
       ]
diff --git a/docs/guide/README.md b/docs/guide/README.md
@@ -38,12 +38,3 @@ With Yarn:
 or with NPM:
 
 `npm run electron:build`
-
-::: warning
-The command names have changed in `v1.0.0-rc.4`. If you are using an older version, the command names are:
-`yarn serve:electron`
-and
-`yarn build:electron`.
-
-Replace `yarn` with `npm run` if you are using npm.
-:::
diff --git a/docs/guide/commonIssues.md b/docs/guide/commonIssues.md
@@ -32,34 +32,18 @@ if (isDevelopment && !process.env.IS_TEST) {
 }
 ```
 
-## Strict mime-type error when running a built app
-
-:::tip Notice
-As of v1.0.0-rc.5, this tag is no longer necessary. You can remove it if you wish.
-:::
-
-This is likely caused because you are missing code in your `public/index.html` file. To add it, simply run `vue invoke electron-builder`. This will re-invoke the generator of VCP Electron Builder. Any missing code will be detected and added automatically. If you would not like to re-invoke the generator, you can paste this code into the top of the `<head>` of your `public/index.html`:
-
-```html
-<% if (BASE_URL === './') { %><base href="app://./" /><% } %>
-```
-
 ## Exceptions in `async` functions not getting logged to console
 
 This bug can be fixed by adding the following code to the entrypoint of your Vue App `src/main.js`:
 
 ```javascript
-process.on('unhandledRejection', error => {
+process.on('unhandledRejection', (error) => {
   console.error(error)
 })
 ```
 
 See [#118](https://github.com/nklayman/vue-cli-plugin-electron-builder/issues/118) for more details. Thanks to [dspangenberg](https://github.com/dspangenberg) for the fix.
 
-## Electron not opening on Node v11
-
-Make sure you are using Electron v2.0.14+ or v3.0.10+. Also, make sure Node is v11.2.0+. See [#107 (comment)](https://github.com/nklayman/vue-cli-plugin-electron-builder/issues/107#issuecomment-441168465) for more details.
-
 ## Other issues
 
 Many issues can be solved by re-invoking the generator of Vue CLI Plugin Electron Builder. This allows it to add newer code to your project files. You may need to do this after upgrading the plugin.
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
@@ -47,13 +47,13 @@ module.exports = {
   },
   pluginOptions: {
     electronBuilder: {
-      chainWebpackMainProcess: config => {
+      chainWebpackMainProcess: (config) => {
         // Chain webpack config for electron main process only
       },
-      chainWebpackRendererProcess: config => {
+      chainWebpackRendererProcess: (config) => {
         // Chain webpack config for electron renderer process only
         // The following example will set IS_ELECTRON to true in your app
-        config.plugin('define').tap(args => {
+        config.plugin('define').tap((args) => {
           args[0]['IS_ELECTRON'] = true
           return args
         })
@@ -63,7 +63,7 @@ module.exports = {
       // Provide an array of files that, when changed, will recompile the main process and restart Electron
       // Your main process file will be added by default
       mainProcessWatch: ['src/myFile1', 'src/myFile2'],
-      // [1.0.0-rc.4+] Provide a list of arguments that Electron will be launched with during "electron:serve",
+      // Provide a list of arguments that Electron will be launched with during "electron:serve",
       // which can be accessed from the main process (src/background.js).
       // Note that it is ignored when --debug flag is used with "electron:serve", as you must launch Electron yourself
       // Command line args (excluding --debug, --dashboard, and --headless) are passed to Electron as well
@@ -73,25 +73,11 @@ module.exports = {
 }
 ```
 
-## Node Integration
-
-As of v2.0, electron `nodeIntegration` is disabled by default. This blocks all node APIs such as `require`. This reduces [security risks](https://electronjs.org/docs/tutorial/security#2-do-not-enable-nodejs-integration-for-remote-content), and is a recommended best practice by the electron team. If you need to use native modules such as `fs` or `sqlite` in the renderer process, you can enable `nodeIntegration` in `vue.config.js`:
-
-```js
-module.exports = {
-  pluginOptions: {
-    electronBuilder: {
-      nodeIntegration: true
-    }
-  }
-}
-```
-
 ## Changing the Output Directory
 
-If you don't want your files outputted into dist_electron, you can choose a custom folder in vue-cli-plugin-electron-builder's plugin options. If you are using `v1.0.0-rc.4` or later, you can use the `--dest` argument to change the output dir as well.
+If you don't want your files outputted into dist_electron, you can choose a custom folder in VCPEB's plugin options. You can use the `--dest` argument to change the output dir as well.
 
-**Note: If you are using version 1.0.0-rc.3 or lower, after changing this, you MUST update the main field of your `package.json` to `[new dir]/bundled/background.js`. It is also recommended to add the new directory to your .gitignore file.**
+**Note: It is recommended to add the new directory to your .gitignore file.**
 
 ```javascript
 // vue.config.js
@@ -123,11 +109,11 @@ module.exports = {
 }
 ```
 
-:::tip Tip <Badge text="1.0.0-rc.1+" type="info"/>
+:::tip Tip
 If you decide to add the `@vue/typescript` plugin to your app later on, make sure to re-invoke the generator of VCP-Electron-Builder with `vue invoke electron-builder`. This will automatically insert missing type definitions to your `background.ts` file.
 :::
 
-## Changing the File Loading Protocol <Badge text="1.0.0+" type="info"/>
+## Changing the File Loading Protocol
 
 By default, the `app` protocol is used to load files. This allows you to use ES6 `type="module"` scripts, created by Vue CLI's [modern mode](https://cli.vuejs.org/guide/browser-compatibility.html#modern-mode). If, for some reason, you would like to use a different protocol, set it with the `customFileProtocol` option, and change it in your `background.js` file.
 
@@ -150,11 +136,11 @@ win.loadURL('myCustomProtocol://./index.html') // Change it here as well
 // ...
 ```
 
-## Bundling Options <Badge text="1.0.0-rc.3+" type="info"/>
+## Bundling Options
 
 By default, the app is built in [modern mode](https://cli.vuejs.org/guide/browser-compatibility.html#modern-mode). To disable this, use the `--legacy` argument in the `electron:build` command. If your app is already bundled and just needs to be built with electron-builder, pass the `--skipBundle` arg.
 
-## Electron's Junk Terminal Output <Badge text="1.0.0-rc.3+" type="info"/>
+## Electron's Junk Terminal Output
 
 Electron will sometimes produce a bunch of junk output like so:
 
@@ -181,7 +167,7 @@ VCP Electron Builder will automatically remove this for you (powered by [run-ele
 module.exports = {
   pluginOptions: {
     electronBuilder: {
-      removeElectronJunk: false // True by default
+      removeElectronJunk: false
     }
   }
 }
diff --git a/docs/guide/guide.md b/docs/guide/guide.md
@@ -125,7 +125,7 @@ win = new BrowserWindow({
 
 ## Env Variables
 
-Read [Vue ClI's documentation](https://cli.vuejs.org/guide/mode-and-env.html) to learn about using environment variables in your app. All env variables prefixed with `VUE_APP_` will be available in both the main and renderer processes (Only available in main process since `1.0.0-rc.4`).
+Read [Vue ClI's documentation](https://cli.vuejs.org/guide/mode-and-env.html) to learn about using environment variables in your app. All env variables prefixed with `VUE_APP_` will be available in both the main and renderer processes.
 
 ## How it works
 
diff --git a/docs/guide/recipes.md b/docs/guide/recipes.md
@@ -158,7 +158,7 @@ win = new BrowserWindow({
 If you get the linting error `'__static' is not defined`, add `/* global __static */` in your background file above your imports.
 :::
 
-## Multiple Pages <badge text="v1.1.1+" type="info" />
+## Multiple Pages
 
 > Create multiple Electron windows for each [page](https://cli.vuejs.org/config/#pages)
 
diff --git a/docs/guide/security.md b/docs/guide/security.md
@@ -0,0 +1,57 @@
+# Security
+
+[[toc]]
+
+## Node Integration
+
+As of v2.0 of VCPEB, Electron `nodeIntegration` is disabled by default. This blocks all node APIs such as `require`. This reduces [security risks](https://electronjs.org/docs/tutorial/security#2-do-not-enable-nodejs-integration-for-remote-content), and is a recommended best practice by the Electron team. If you need to use native modules such as `fs` or `sqlite` in the renderer process, you can enable `nodeIntegration` in `vue.config.js`:
+
+```js
+module.exports = {
+  pluginOptions: {
+    electronBuilder: {
+      nodeIntegration: true
+    }
+  }
+}
+```
+
+:::tip IPC With Node Integration
+You can still use [IPC](https://www.electronjs.org/docs/api/ipc-renderer) with `nodeIntegration`. Just create a [preload script](./guide.html#preload-files) with the following code:
+
+```js
+import { ipcRenderer } from 'electron'
+window.ipcRenderer = ipcRenderer
+```
+
+Now, you can access `ipcRenderer` with `window.ipcRenderer` in your Vue app.
+:::
+
+## Loading Local Images/Resources
+
+If WebSecurity is enabled, you won't be able to load resources from the file system, ie `<img src="file://image.png"/>`. [Disabling WebSecurity is strongly discouraged](https://www.electronjs.org/docs/tutorial/security#5-do-not-disable-websecurity), so you should instead use the following technique to load local resources and keep WebSecurity enabled.
+
+Add the following to your main process file (`background.(js|ts)` by default):
+
+```js
+app.on('ready', () => {
+  registerLocalResourceProtocol()
+  ...
+})
+
+function registerLocalResourceProtocol() {
+  protocol.registerFileProtocol('local-resource', (request, callback) => {
+    const url = request.url.replace(/^local-resource:\/\//, '')
+    // Decode URL to prevent errors when loading filenames with UTF-8 chars or chars like "#"
+    const decodedUrl = decodeURI(url) // Needed in case URL contains spaces
+    try {
+      return callback(decodedUrl)
+    }
+    catch (error) {
+      console.error('ERROR: registerLocalResourceProtocol: Could not get file path:', error)
+    }
+  })
+}
+```
+
+Then, simply prefix local image urls with `local-resource://`, ie `<img src="local-resource://image.png"/>`
