Merge pull request #165 from johnb8/electron-plugin

johnb8 · web-flow · commit c6e8c2ad7ec9 · 2021-07-27T12:28:36.000-06:00
Electron package
diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
@@ -21,7 +21,8 @@ jobs:
         node-version: ${{ matrix.node-version }}
     - uses: bahmutov/npm-install@v1
 
+    - run: yarn playwright install-deps chromium
     - run: yarn build
-    - run: yarn test --testTimeout 20000
+    - run: xvfb-run yarn test --testTimeout 20000
       env: { CI: 1 }
 
diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml
@@ -21,6 +21,7 @@ jobs:
         node-version: ${{ matrix.node-version }}
     - uses: bahmutov/npm-install@v1
 
+    - run: yarn playwright install-deps chromium
     - run: yarn build
     - run: yarn test --testTimeout 20000
       env: { CI: 1 }
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -9,7 +9,7 @@ jobs:
   # for branches, we only need to check Linux + Node LTS
   # note that we do linting here, but not on Windows / MacOS (no need to)
   linux-and-lts:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
 
     strategy:
       matrix:
@@ -22,12 +22,17 @@ jobs:
       with:
         node-version: ${{ matrix.node-version }}
     - uses: bahmutov/npm-install@v1
+    - run: yarn playwright install-deps chromium
     - run: yarn build
     - run: yarn build:es
     - run: yarn build:all
     - run: yarn lint
+    - run: xvfb-run yarn test --coverage --testTimeout 20000
+      env: { CI: 1 }
+      if: matrix.os == 'ubuntu-latest'
     - run: yarn test --coverage --testTimeout 20000
       env: { CI: 1 }
+      if: matrix.os != 'ubuntu-latest'
 
     # sanity check that the rollup plugin made a file without needing to loadConfig
     - run: yarn --cwd ./examples/rollup-project start
@@ -62,5 +67,6 @@ jobs:
           ./app-config-webpack/coverage/coverage-final.json,
           ./app-config-rollup/coverage/coverage-final.json,
           ./app-config-vite/coverage/coverage-final.json,
+          ./app-config-electron/coverage/coverage-final.json,
         fail_ci_if_error: true
         verbose: true
diff --git a/.github/workflows/publishing.yml b/.github/workflows/publishing.yml
@@ -34,6 +34,12 @@ jobs:
         token: ${{ secrets.NPM_TOKEN }}
         access: public
         package: ./app-config-cypress/package.json
+    - name: app-config-electron
+      uses: JS-DevTools/npm-publish@v1
+      with:
+        token: ${{ secrets.NPM_TOKEN }}
+        access: public
+        package: ./app-config-electron/package.json
     - name: app-config-default-extensions
       uses: JS-DevTools/npm-publish@v1
       with:
diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml
@@ -21,6 +21,7 @@ jobs:
         node-version: ${{ matrix.node-version }}
     - uses: bahmutov/npm-install@v1
 
+    - run: yarn playwright install-deps chromium
     - run: yarn build
     - run: yarn test --testTimeout 20000
       env: { CI: 1 }
diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,8 @@ node_modules/
 
 # app-config files, when developing
 .app-config.*
+# keep example files though
+!examples/**/.app-config.*
 
 # common build sites
 dist/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -53,6 +53,7 @@ If you are adding anything new or changing behavior, please add applicable tests
 - `@app-config/webpack`: webpack plugin
 - `@app-config/rollup`: rollup plugin
 - `@app-config/vite`: vite plugin
+- `@app-config/electron`: injects config into Electron renderer processes
 - `@app-config/main`: main config singleton and loading logic
 - `@lcdev/app-config`: alias for `@app-config/main`
 - `@lcdev/app-config-webpack-plugin`: alias for `@app-config/webpack`
diff --git a/app-config-electron/.eslintrc.js b/app-config-electron/.eslintrc.js
@@ -0,0 +1 @@
+module.exports = require('@lcdev/eslint-config/cwd')(__dirname);
diff --git a/app-config-electron/README.md b/app-config-electron/README.md
@@ -0,0 +1,51 @@
+# App Config Electron
+
+Easily inject `app-config` values into Electron renderer processes. An example project is provided [here.](https://github.com/launchcodedev/app-config/tree/master/examples/electron-project)
+
+## Usage
+
+### 1. Install App Config and the Electron Package
+
+```shell
+yarn add @app-config/main @app-config/electron
+```
+
+Or, if you use NPM.
+
+```shell
+npm i @app-config/main @app-config/electron
+```
+
+### 2. Load your config with any options you need in the main Electron process before creating any windows
+```typescript
+app.whenReady().then(() => {
+  loadConfig().then(() => {
+    const mainWindow = new BrowserWindow();
+
+    mainWindow.loadFile('./index.html')
+  });
+});
+```
+
+### 3. Insert the App Config preload script into your `BrowserWindow` `webPreferences`
+
+Pass your config and optionally any other `BrowserWindow` `webPreferences` you need to `addAppConfigPreload`.
+```typescript
+app.whenReady().then(() => {
+  loadConfig().then(() => {
+    const mainWindow = new BrowserWindow({
+      webPreferences: addAppConfigPreload(config),
+    });
+
+    mainWindow.loadFile('./index.html')
+  });
+});
+```
+
+### 4. Your App Config values are now available!
+
+They can be found in `window._appConfig` or in `config` if using `@app-config/main` in your web page (when using `@app-config/webpack` with `headerInjection` or `@app-config/vite` with `readGlobal`). It's also available in `config` in the main Electron process.
+
+Your app will need to be restarted to reflect any configuration changes.
+
+Setting `contextIsolation` to `true` in the `browserOptions` of your `BrowserWindow` settings is required for this package to work. We set this for you, but if your app requres `contextIsolation` to be `false` using this package will break your app.
diff --git a/app-config-electron/package.json b/app-config-electron/package.json
@@ -0,0 +1,44 @@
+{
+  "name": "@app-config/electron",
+  "description": "Exposes app-config values to Electron render processes",
+  "version": "2.6.0",
+  "license": "MPL-2.0",
+  "author": {
+    "name": "Launchcode",
+    "email": "admin@lc.dev",
+    "url": "https://lc.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/launchcodedev/app-config.git"
+  },
+  "main": "dist/index.js",
+  "module": "dist/es/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "/dist",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "build:es": "tsc -b tsconfig.es.json",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "lint": "eslint src",
+    "fix": "eslint --fix src",
+    "test": "jest",
+    "prepublishOnly": "yarn clean && yarn build && yarn build:es"
+  },
+  "dependencies": {
+    "@app-config/main": "^2.6.0",
+    "@app-config/logging": "^2.6.0"
+  },
+  "peerDependencies": {
+    "electron": "13 || 12 || 11 || 10"
+  },
+  "devDependencies": {},
+  "prettier": "@lcdev/prettier",
+  "jest": {
+    "preset": "@lcdev/jest"
+  }
+}
diff --git a/app-config-electron/src/index.ts b/app-config-electron/src/index.ts
@@ -0,0 +1,28 @@
+import type { WebPreferences } from 'electron';
+import type { ExportedConfig } from '@app-config/main';
+import * as path from 'path';
+
+export function addAppConfigPreload(config: ExportedConfig, baseWebPreferences?: WebPreferences) {
+  let webPreferences: WebPreferences = {};
+
+  if (baseWebPreferences) {
+    webPreferences = baseWebPreferences;
+  }
+
+  const userPreload = baseWebPreferences?.preload;
+  const userArguments = baseWebPreferences?.additionalArguments;
+
+  const preloadArguments = userArguments || [];
+
+  preloadArguments.push(`--app-config=${JSON.stringify(config)}`);
+
+  if (userPreload) {
+    preloadArguments.push(`--user-preload=${userPreload}`);
+  }
+
+  webPreferences.preload = path.join(__dirname, 'preloader.js');
+  webPreferences.additionalArguments = preloadArguments;
+  webPreferences.contextIsolation = true;
+
+  return webPreferences;
+}
diff --git a/app-config-electron/src/preloader.ts b/app-config-electron/src/preloader.ts
@@ -0,0 +1,32 @@
+import { contextBridge } from 'electron';
+import { inspect } from 'util';
+import { logger } from '@app-config/logging';
+import type { ExportedConfig } from '@app-config/main';
+
+let additionalPreload: string | undefined;
+let config: ExportedConfig | undefined;
+
+for (const arg of process.argv) {
+  if (arg.startsWith('--user-preload=')) {
+    additionalPreload = arg.substr(15);
+  }
+
+  if (arg.startsWith('--app-config=')) {
+    try {
+      config = JSON.parse(arg.substr(13)) as ExportedConfig;
+    } catch (err) {
+      logger.error(`Got invalid JSON from config: ${inspect(err)}`);
+    }
+  }
+}
+
+if (config) {
+  contextBridge.exposeInMainWorld('_appConfig', config);
+  logger.info(`⚙️ Injected app-config`);
+}
+
+// This seems to be how electron does preload scripts https://github.com/electron/electron/issues/2406 maybe there's a better way?
+/* eslint-disable import/no-dynamic-require, global-require */
+if (additionalPreload) {
+  require(additionalPreload);
+}
diff --git a/app-config-electron/tsconfig.es.json b/app-config-electron/tsconfig.es.json
@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "target": "es2019",
+    "module": "es2020",
+    "outDir": "./dist/es"
+  }
+}
diff --git a/app-config-electron/tsconfig.json b/app-config-electron/tsconfig.json
@@ -0,0 +1,16 @@
+{
+  "extends": "@lcdev/tsconfig",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "lib": [
+      "esnext",
+      "dom"
+    ],  
+  },
+  "include": ["src"],
+  "exclude": ["node_modules"],
+  "references": [
+    { "path": "../app-config-test-utils" }
+  ]
+}
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -55,6 +55,10 @@ module.exports = {
         title: 'Rollup',
         path: '/guide/rollup',
       },
+      {
+        title: 'Electron',
+        path: '/guide/electron',
+      },
       {
         title: 'Deployment',
         path: '/guide/deployment/',
diff --git a/docs/guide/electron.md b/docs/guide/electron.md
@@ -0,0 +1,69 @@
+---
+title: Electron Plugin
+---
+
+::: tip Before Reading
+Head on over to the [Introduction](../intro/) or [Quick Start](../intro/quick-start) if you haven't already.
+:::
+
+An example project is available on [GitHub](https://github.com/launchcodedev/app-config/tree/master/examples/electron-project)
+
+The Electron plugin is a separate package, which you'll need to install:
+
+```sh
+yarn add -D @app-config/electron@2
+```
+
+First, you'll want to load your config in the main Electron process just as you would in any regular Node project, except you may want to wait until your Electron app is ready.
+
+```typescript
+import { app, BrowserWindow } from 'electron';
+import { addAppConfigPreload } from '@app-config/electron';
+import { loadConfig, config } from '@app-config/main';
+
+app.whenReady().then(() => {
+  loadConfig().then(() => {
+    // run your main Electron code here
+  });
+});
+```
+
+Now you'll probably want to open a browser window. To give the browser window access to your config, you'll need to include App Config's preload script in the `webPreferences` of your browser window:
+
+::: warning Note
+The Electron plugin requires `contextIsolation` in your browser window's `webPreferences` to be `true`. This is best security practice, but if your app requires it to be `false` the Electron plugin will not work. `addAppConfigPreload` ensures this is set correctly.
+:::
+
+```typescript
+app.whenReady().then(() => {
+  loadConfig().then(() => {
+    const mainWindow = new BrowserWindow({
+      webPreferences: addAppConfigPreload(config),
+    });
+
+    mainWindow.loadFile('./index.html');
+  });
+});
+
+```
+
+If you have other `webPreferences` you need to set in addition to the ones that will be set by App Config (like another preload script or parameters), pass them as a second parameter to `addAppConfigPreload`:
+
+```typescript
+app.whenReady().then(() => {
+  loadConfig().then(() => {
+      const mainWindow = new BrowserWindow({
+        webPreferences: addAppConfigPreload(config, {
+          preload: './my-preload.js',
+          additionalArguments: '--my-argument',
+        }),
+      });
+
+    mainWindow.loadFile('./index.html');
+  });
+});
+```
+
+And that's it! Now your config is available in `window._appConfig` in your browser window. You'll need to restart your app to reflect any configuration changes.
+
+When using our Webpack or Vite plugins (when using the `headerInjection` or `readGlobal` options respectively) it will also be available in the main `config` object if you're using `@app-config/main`.
diff --git a/examples/electron-project/.app-config.meta.yml b/examples/electron-project/.app-config.meta.yml
@@ -0,0 +1,2 @@
+generate:
+  - file: './src/@types/lcdev__app-config/index.d.ts'
diff --git a/examples/electron-project/.app-config.schema.yml b/examples/electron-project/.app-config.schema.yml
@@ -0,0 +1,10 @@
+type: object
+additionalProperties: false
+
+required:
+  - externalApiUrl
+
+properties:
+  externalApiUrl:
+    type: string
+    format: uri
diff --git a/examples/electron-project/.app-config.yml b/examples/electron-project/.app-config.yml
@@ -0,0 +1 @@
+externalApiUrl: https://example.com
diff --git a/examples/electron-project/README.md b/examples/electron-project/README.md
@@ -0,0 +1,10 @@
+## Electron Example Project
+
+This project demonstrates a configuration being injected into an Electron renderer process.
+
+## Usage
+```
+yarn build
+
+yarn start
+```
diff --git a/examples/electron-project/index.html b/examples/electron-project/index.html
diff --git a/examples/electron-project/package.json b/examples/electron-project/package.json
diff --git a/examples/electron-project/src/main.test.ts b/examples/electron-project/src/main.test.ts
diff --git a/examples/electron-project/src/main.ts b/examples/electron-project/src/main.ts
diff --git a/examples/electron-project/src/preload-test.ts b/examples/electron-project/src/preload-test.ts
diff --git a/examples/electron-project/tsconfig.json b/examples/electron-project/tsconfig.json
diff --git a/new-version.sh b/new-version.sh
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+module.exports = require('@lcdev/eslint-config/cwd')(__dirname);`