feat: add module exports for preload scripts

Author: samuelmaddock

build/esbuild/esbuild.config.base.js

@@ -36,6 +36,7 @@ const EXTERNAL_BASE = [
   'node:crypto',
   'node:events',
   'node:fs',
+  'node:module',
   'node:os',
   'node:path',
   'node:stream',

packages/electron-chrome-extensions/.gitignore

@@ -1,2 +1,3 @@
 dist
-*.map
+*.map
+*.preload.js

packages/electron-chrome-extensions/README.md

@@ -48,7 +48,7 @@ Multi-tab browser with full support for Chrome extension APIs.
 
 ```js
 const { app, session, BrowserWindow } = require('electron')
-const { ElectronChromeExtensions } = require('electron-chrome-extensions')(
+const { ElectronChromeExtensions } = require('electron-chrome-extensions')
 
 app.whenReady().then(() => {
   const browserSession = session.fromPartition('persist:custom')
@@ -93,6 +93,34 @@ app.whenReady().then(() => {
 })
 ```
 
+### Packaging the preload script
+
+This module uses a [preload script](https://www.electronjs.org/docs/latest/tutorial/tutorial-preload#what-is-a-preload-script).
+When packaging your application, it's required that the preload script is included. This can be
+handled in two ways:
+
+1. Include `node_modules` in your packaged app. This allows `electron-chrome-extensions/preload` to
+   be resolved.
+2. In the case of using JavaScript bundlers, you may need to copy the preload script next to your
+   app's entry point script. You can try using
+   [copy-webpack-plugin](https://github.com/webpack-contrib/copy-webpack-plugin),
+   [vite-plugin-static-copy](https://github.com/sapphi-red/vite-plugin-static-copy),
+   or [rollup-plugin-copy](https://github.com/vladshcherbin/rollup-plugin-copy) depending on your app's
+   configuration.
+
+Here's an example for webpack configurations:
+
+```js
+module.exports = {
+  entry: './index.js',
+  plugins: [
+    new CopyWebpackPlugin({
+      patterns: [require.resolve('electron-chrome-extensions/preload')],
+    }),
+  ],
+}
+```
+
 ## API
 
 ### Class: ElectronChromeExtensions
@@ -104,7 +132,6 @@ app.whenReady().then(() => {
 - `options` Object
   - `license` String - Distribution license compatible with your application. See LICENSE.md for more details. \
      Valid options include `GPL-3.0`, `Patron-License-2020-11-19`
-  - `modulePath` String (optional) - Path to electron-chrome-extensions module files. Might be needed if JavaScript bundlers like Webpack are used in your build process.
   - `session` Electron.Session (optional) - Session which should support
     Chrome extension APIs. `session.defaultSession` is used by default.
   - `createTab(details) => Promise<[Electron.WebContents, Electron.BrowserWindow]>` (optional) -
@@ -224,7 +251,7 @@ To enable the element on a webpage, you must define a preload script which injec
 Inject the browserAction API to make the `<browser-action-list>` element accessible in your application.
 
 ```js
-import { injectBrowserAction } from 'electron-chrome-extensions/dist/browser-action'
+import { injectBrowserAction } from 'electron-chrome-extensions/browser-action'
 
 // Inject <browser-action-list> element into our page
 if (location.href === 'webui://browser-chrome.html') {

packages/electron-chrome-extensions/esbuild.config.js

@@ -3,7 +3,7 @@ const { createConfig, build, EXTERNAL_BASE } = require('../../build/esbuild/esbu
 
 console.log(`building ${packageJson.name}`)
 
-const external = [...EXTERNAL_BASE]
+const external = [...EXTERNAL_BASE, 'electron-chrome-extensions/preload']
 
 const browserConfig = createConfig({
   entryPoints: ['src/index.ts'],
@@ -25,7 +25,7 @@ build(browserESMConfig)
 
 const preloadConfig = createConfig({
   entryPoints: ['src/preload.ts'],
-  outfile: 'dist/preload.js',
+  outfile: 'dist/chrome-extension-api.preload.js',
   platform: 'browser',
   external,
   sourcemap: false,

packages/electron-chrome-extensions/package.json

@@ -11,11 +11,17 @@
       "import": "./dist/esm/index.mjs",
       "require": "./dist/cjs/index.js"
     },
+    "./browser-action": {
+      "types": "./dist/types/browser-action.d.ts",
+      "import": "./dist/esm/browser-action.mjs",
+      "require": "./dist/cjs/browser-action.js"
+    },
     "./dist/browser-action": {
       "types": "./dist/types/browser-action.d.ts",
       "import": "./dist/esm/browser-action.mjs",
       "require": "./dist/cjs/browser-action.js"
-    }
+    },
+    "./preload": "./dist/chrome-extension-api.preload.js"
   },
   "scripts": {
     "build": "yarn clean && tsc && node esbuild.config.js",

packages/electron-chrome-extensions/src/browser/index.ts

@@ -1,7 +1,8 @@
 import { session as electronSession } from 'electron'
 import { EventEmitter } from 'node:events'
 import path from 'node:path'
-import { promises as fs } from 'node:fs'
+import { existsSync } from 'node:fs'
+import { createRequire } from 'node:module'
 
 import { BrowserActionAPI } from './api/browser-action'
 import { TabsAPI } from './api/tabs'
@@ -27,6 +28,31 @@ function checkVersion() {
   }
 }
 
+function resolvePreloadPath(modulePath?: string) {
+  // Attempt to resolve preload path from module exports
+  try {
+    return createRequire(__dirname).resolve('electron-chrome-extensions/preload')
+  } catch (error) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.error(error)
+    }
+  }
+
+  const preloadFilename = 'chrome-extension-api.preload.js'
+
+  // Deprecated: use modulePath if provided
+  if (modulePath) {
+    process.emitWarning(
+      'electron-chrome-extensions: "modulePath" is deprecated and will be removed in future versions.',
+      { type: 'DeprecationWarning' },
+    )
+    return path.join(modulePath, 'dist', preloadFilename)
+  }
+
+  // Fallback to preload relative to entrypoint directory
+  return path.join(__dirname, preloadFilename)
+}
+
 export interface ChromeExtensionOptions extends ChromeExtensionImpl {
   /**
    * License used to distribute electron-chrome-extensions.
@@ -44,6 +70,8 @@ export interface ChromeExtensionOptions extends ChromeExtensionImpl {
   /**
    * Path to electron-chrome-extensions module files. Might be needed if
    * JavaScript bundlers like Webpack are used in your build process.
+   *
+   * @deprecated See "Packaging the preload script" in the readme.
    */
   modulePath?: string
 }
@@ -60,7 +88,6 @@ export class ElectronChromeExtensions extends EventEmitter {
   }
 
   private ctx: ExtensionContext
-  private modulePath: string
 
   private api: {
     browserAction: BrowserActionAPI
@@ -78,7 +105,7 @@ export class ElectronChromeExtensions extends EventEmitter {
   constructor(opts: ChromeExtensionOptions) {
     super()
 
-    const { license, session = electronSession.defaultSession, modulePath, ...impl } = opts || {}
+    const { license, session = electronSession.defaultSession, ...impl } = opts || {}
 
     checkVersion()
     checkLicense(license)
@@ -99,8 +126,6 @@ export class ElectronChromeExtensions extends EventEmitter {
       store,
     }
 
-    this.modulePath = modulePath || path.join(__dirname, '../..')
-
     this.api = {
       browserAction: new BrowserActionAPI(this.ctx),
       contextMenus: new ContextMenusAPI(this.ctx),
@@ -115,7 +140,7 @@ export class ElectronChromeExtensions extends EventEmitter {
     }
 
     this.listenForExtensions()
-    this.prependPreload()
+    this.prependPreload(opts.modulePath)
 
     // Register crx:// protocol in default session for convenience
     if (this.ctx.session !== electronSession.defaultSession) {
@@ -129,10 +154,10 @@ export class ElectronChromeExtensions extends EventEmitter {
     })
   }
 
-  private async prependPreload() {
+  private async prependPreload(modulePath?: string) {
     const { session } = this.ctx
 
-    const preloadPath = path.join(this.modulePath, 'dist/preload.js')
+    const preloadPath = resolvePreloadPath(modulePath)
 
     if ('registerPreloadScript' in session) {
       session.registerPreloadScript({
@@ -150,15 +175,12 @@ export class ElectronChromeExtensions extends EventEmitter {
       session.setPreloads([...session.getPreloads(), preloadPath])
     }
 
-    let preloadExists = false
-    try {
-      const stat = await fs.stat(preloadPath)
-      preloadExists = stat.isFile()
-    } catch {}
-
-    if (!preloadExists) {
+    if (!existsSync(preloadPath)) {
       console.error(
-        `Unable to access electron-chrome-extensions preload file (${preloadPath}). Consider configuring the 'modulePath' constructor option.`,
+        new Error(
+          `electron-chrome-extensions: Preload file not found at "${preloadPath}". ` +
+            'See "Packaging the preload script" in the readme.',
+        ),
       )
     }
   }

packages/electron-chrome-web-store/.gitignore

@@ -1 +1,2 @@
-dist
+dist
+*.preload.js

packages/electron-chrome-web-store/README.md

@@ -57,6 +57,34 @@ app.whenReady().then(async () => {
 })
 ```
 
+### Packaging the preload script
+
+This module uses a [preload script](https://www.electronjs.org/docs/latest/tutorial/tutorial-preload#what-is-a-preload-script).
+When packaging your application, it's required that the preload script is included. This can be
+handled in two ways:
+
+1. Include `node_modules` in your packaged app. This allows `electron-chrome-web-store/preload` to
+   be resolved.
+2. In the case of using JavaScript bundlers, you may need to copy the preload script next to your
+   app's entry point script. You can try using
+   [copy-webpack-plugin](https://github.com/webpack-contrib/copy-webpack-plugin),
+   [vite-plugin-static-copy](https://github.com/sapphi-red/vite-plugin-static-copy),
+   or [rollup-plugin-copy](https://github.com/vladshcherbin/rollup-plugin-copy) depending on your app's
+   configuration.
+
+Here's an example for webpack configurations:
+
+```js
+module.exports = {
+  entry: './index.js',
+  plugins: [
+    new CopyWebpackPlugin({
+      patterns: [require.resolve('electron-chrome-web-store/preload')],
+    }),
+  ],
+}
+```
+
 ## API
 
 ### `installChromeWebStore`
@@ -65,7 +93,6 @@ Installs Chrome Web Store support in the specified session.
 
 - `options`
   - `session`: The Electron session to enable the Chrome Web Store in. Defaults to `session.defaultSession`.
-  - `modulePath`: The path to the 'electron-chrome-web-store' module.
   - `extensionsPath`: The path to the extensions directory. Defaults to 'Extensions/' in the app's userData path.
   - `autoUpdate`: Whether to auto-update web store extensions at startup and once every 5 hours. Defaults to true.
   - `loadExtensions`: A boolean indicating whether to load extensions installed by Chrome Web Store. Defaults to true.

packages/electron-chrome-web-store/esbuild.config.js

@@ -3,7 +3,7 @@ const { createConfig, build, EXTERNAL_BASE } = require('../../build/esbuild/esbu
 
 console.log(`building ${packageJson.name}`)
 
-const external = [...EXTERNAL_BASE, 'adm-zip', 'pbf']
+const external = [...EXTERNAL_BASE, 'adm-zip', 'pbf', 'electron-chrome-web-store/preload']
 
 const esmOnlyModules = ['pbf']
 
@@ -26,8 +26,8 @@ build(browserConfig)
 build(browserESMConfig)
 
 const preloadConfig = createConfig({
-  entryPoints: ['src/renderer/web-store-preload.ts'],
-  outfile: 'dist/renderer/web-store-preload.js',
+  entryPoints: ['src/renderer/chrome-web-store.preload.ts'],
+  outfile: 'dist/chrome-web-store.preload.js',
   platform: 'browser',
   external,
   sourcemap: false,

packages/electron-chrome-web-store/package.json

@@ -10,7 +10,8 @@
       "types": "./dist/types/browser/index.d.ts",
       "import": "./dist/esm/browser/index.mjs",
       "require": "./dist/cjs/browser/index.js"
-    }
+    },
+    "./preload": "./dist/chrome-web-store.preload.js"
   },
   "scripts": {
     "build": "yarn clean && tsc && node esbuild.config.js",