@dimensional-innovations/electron-background 2.3.0 → 3.0.0

package/README.md

@@ -1,99 +1,390 @@
 # @dimensional-innovations/electron-background
 
-electron-background aims to simplify electron apps by providing a simple api to customize the electron application.
+A TypeScript library that simplifies Electron app initialization through a plugin-based architecture.
 
 ## Getting Started
 
-### Install
-Add the package using npm or yarn:
-```bash
-npm install @dimensional-innovations/electron-background
-```
+### Installation
 
 ```bash
-yarn add @dimensional-innovations/electron-background
+npm install @dimensional-innovations/electron-background
 ```
 
 ### Setup for Vue CLI / Webpack
 
-If you are using the Vue CLI, add the following to your main or background file. 
+If you are using the Vue CLI, add the following to your main or background file.
+
 ```typescript
-import { AutoUpdater, DevTools, init, KioskBrowserWindow, PrivilegedSchemes, StaticFileDir, TouchEvents } from '@dimensional-innovations/electron-background';
+import path from 'path';
+import {
+  init,
+  KioskBrowserWindow,
+  PrivilegedSchemes,
+  StaticFileDir,
+  AutoUpdater,
+  DevTools,
+  DevToolExtensions,
+} from '@dimensional-innovations/electron-background';
 
 init({
-  appUrl: process.env.WEBPACK_DEV_URL ? process.env.WEBPACK_DEV_URL : 'app://index.html',
+  windows: [
+    () => new KioskBrowserWindow({ 
+      appUrl: process.env.WEBPACK_DEV_URL ? process.env.WEBPACK_DEV_URL : 'app://index.html' 
+    }),
+  ],
   plugins: [
-    new AutoUpdater({ channel: 'stable' }),
-    new DevTools(),
-    new KioskBrowserWindow(),
     new PrivilegedSchemes(['app']),
-    new StaticFileDir('app', __dirname),
-    new TouchEvents(),
-  ]
+    new StaticFileDir('app', path.join(__dirname, '../renderer')),
+    new AutoUpdater({ channel: 'stable' }),
+    new DevTools([DevToolExtensions.VUEJS_DEVTOOLS]),
+  ],
 });
 ```
 
 ### Setup for Vite
 
-If you are using Vite, add the following to your main or background file. 
+If you are using Vite, add the following to your main or background file.
+
 ```typescript
-import { AutoUpdater, DevTools, init, KioskBrowserWindow, TouchEvents } from '@dimensional-innovations/electron-background';
-import { join } from 'path';
+import path from 'path';
+import {
+  init,
+  KioskBrowserWindow,
+  PrivilegedSchemes,
+  StaticFileDir,
+  AutoUpdater,
+  DevTools,
+  DevToolExtensions,
+} from '@dimensional-innovations/electron-background';
 
 init({
-  appUrl: process.env['ELECTRON_RENDERER_URL']
-    ? process.env['ELECTRON_RENDERER_URL']
-    : `file://${join(__dirname, '../renderer/index.html')}`,
+  windows: [
+    () => new KioskBrowserWindow({ 
+      appUrl: process.env['ELECTRON_RENDERER_URL']
+        ? process.env['ELECTRON_RENDERER_URL']
+        : `file://${path.join(__dirname, '../renderer/index.html')`,
+    }),
+  ],
   plugins: [
     new AutoUpdater({ channel: 'stable' }),
     new DevTools(),
     new KioskBrowserWindow(),
-    new TouchEvents(),
   ]
 });
 ```
 
-## Plugins
+---
+
+## Windows
+
+Windows are defined as factory functions in the `windows` array. Each factory is called after `app.whenReady()` resolves, satisfying Electron's requirement that `BrowserWindow` instances are not created before the app is ready.
+
+```typescript
+init({
+  windows: [
+    () => new KioskBrowserWindow({ appUrl: '...' }),
+  ],
+});
+```
+
+### AppBrowserWindow
+
+The base window class. All built-in window classes extend it. Extends Electron's `BrowserWindow` with an `appUrl` constructor option and a `loadApp()` method.
+
+```typescript
+() => new AppBrowserWindow({
+  appUrl: 'app://index.html',
+  width: 1280,
+  height: 720,
+})
+```
+
+All standard `BrowserWindowConstructorOptions` are supported in addition to `appUrl`.
+
+---
+
+### KioskBrowserWindow
+
+Runs the window in kiosk mode when the application is packaged. In development it behaves as a normal window, making it easy to inspect and resize.
+
+```typescript
+() => new KioskBrowserWindow({ appUrl: 'app://index.html' })
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `appUrl` | `string` | — | The URL to load. |
+| `screen` | `'primary' \| 'secondary' \| number` | `'primary'` | The display to run kiosk mode on. Use `'secondary'` for the first non-primary display, or a zero-based index for a specific display. |
+| `...BrowserWindowConstructorOptions` | | | All standard Electron options are supported. |
+
+**Second parameter:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `enabled` | `boolean` | `app.isPackaged` | Set to `true` to force kiosk behavior in development. |
 
-By default, the init method creates a BrowserWindow and loads the specified application into the window. All other features of an application are managed through plugins. Each plugin customizes the application instance during the init process. The built-in plugins are listed below.
+**Examples:**
 
-If a feature you need isn't listed below, you can still add it to the init script by defining the plugin in your application. For example, if we wanted to customize the autoplay policy flag in electron, we would add the following to our init method.
 ```typescript
-import { init } from '@dimensional-innovations/electron-background';
-import { app } from 'electron';
+// Default — kiosk on the primary display when packaged
+() => new KioskBrowserWindow({ appUrl: 'app://index.html' })
 
+// Kiosk on the secondary display
+() => new KioskBrowserWindow({ appUrl: 'app://index.html', screen: 'secondary' })
+
+// Kiosk on the display at index 2
+() => new KioskBrowserWindow({ appUrl: 'app://index.html', screen: 2 })
+
+// Force kiosk behavior in development
+() => new KioskBrowserWindow({ appUrl: 'app://index.html' }, true)
+```
+
+---
+
+### FullScreenBrowserWindow
+
+Ensures the window always occupies the full bounds of a display. When packaged, the window snaps to the target display on `ready-to-show` and automatically re-snaps when display configuration changes (display added, removed, or resized). In development it behaves as a normal window.
+
+Prefer `FullScreenBrowserWindow` over `KioskBrowserWindow` when:
+- Running multiple windows across different displays
+- A window needs to span multiple displays (see [spanning multiple displays](#example-window-spanning-multiple-displays))
+
+```typescript
+() => new FullScreenBrowserWindow({ appUrl: 'app://index.html' })
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `appUrl` | `string` | — | The URL to load. |
+| `screen` | `'primary' \| 'secondary' \| number` | `'primary'` | The display to occupy. Use `'secondary'` for the first non-primary display, or a zero-based index for a specific display. |
+| `...BrowserWindowConstructorOptions` | | | All standard Electron options are supported. |
+
+**Second parameter:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `enabled` | `boolean` | `app.isPackaged` | Set to `true` to force fullscreen behavior in development. |
+
+**Example — multiple windows, one per display:**
+
+```typescript
 init({
-  appUrl: ...,
+  windows: [
+    () => new FullScreenBrowserWindow({ appUrl: 'app://index.html', screen: 'primary' }),
+    () => new FullScreenBrowserWindow({ appUrl: 'app://index.html', screen: 'secondary' }),
+  ],
   plugins: [
-    ...,
-    { beforeReady: () => app.commandLine.appendSwitch('autoplay-policy', 'no-user-gesture-required') }
-    ...,
-  ]
+    new PrivilegedSchemes(['app']),
+    new StaticFileDir('app', path.join(__dirname, '../renderer')),
+    new AutoUpdater({ channel: 'stable' }),
+  ],
 });
 ```
 
-### AutoUpdater
-Starts the auto update process, checking for updates every 3 minutes and automatically installing the update once one is found.
+Each window independently tracks its target display and re-snaps when the display configuration changes.
 
-For more info, see https://www.electron.build/auto-update
+---
 
-### DevTools
-Installs dev tools extensions and opens the devTools panel.
+## Plugins
 
-### KioskBrowserWindow
-Enables kiosk mode in the BrowserWindow when the application is packaged.
+Plugins implement the `InitPlugin` interface and hook into one or more phases of the initialization lifecycle.
+
+### Lifecycle
+
+```
+beforeReady → app.whenReady() → afterReady → [per window] beforeLoad → loadApp() → afterLoad
+```
+
+| Phase | Context | Typical use |
+|-------|---------|-------------|
+| `beforeReady` | No window | Registering privileged schemes |
+| `afterReady` | No window | App-level setup after Electron is ready |
+| `beforeLoad` | Window available | Installing extensions, attaching window event handlers |
+| `afterLoad` | Window available | Starting background services, adjusting window state after load |
 
-### BetterStackHeartbeat
-Starts a heartbeat, which reports uptime to betteruptime.com. Requires `heartbeatApiKey` in options.
+The context object passed to each phase contains:
+- `log` — an `electron-log` instance. Use this instead of `console` so output is captured in log files.
+- `browserWindow` — the `AppBrowserWindow` instance. Only available in `beforeLoad` and `afterLoad`.
 
-### PrivilegedSchemes
-Registers schemes as privileged.
+---
+
+### Built-in Plugins
+
+#### AutoUpdater
+
+Checks for and automatically installs updates every 3 minutes using `electron-updater`. Only runs when packaged by default.
+
+```typescript
+new AutoUpdater({ channel: 'stable' })
+
+// Custom channel
+new AutoUpdater({ channel: 'beta' })
+
+// Force-enable in development
+new AutoUpdater({ channel: 'stable' }, true)
+```
 
-### StaticFileDir
-Registers a custom scheme to serve static files. 
+#### DevTools
 
-### TouchEvents
-Enables touch events in the app.
+Installs browser extensions and opens DevTools. Only runs in development by default.
+
+```typescript
+import { DevTools, DevToolExtensions } from '@dimensional-innovations/electron-background';
+
+new DevTools([DevToolExtensions.VUEJS_DEVTOOLS])
+new DevTools([DevToolExtensions.REACT_DEVELOPER_TOOLS, DevToolExtensions.REDUX_DEVTOOLS])
+```
+
+Available extensions: `VUEJS_DEVTOOLS`, `REACT_DEVELOPER_TOOLS`, `REDUX_DEVTOOLS`, `MOBX_DEVTOOLS`, `EMBER_INSPECTOR`, `BACKBONE_DEBUGGER`, `JQUERY_DEBUGGER`.
+
+#### SingleInstance
+
+Ensures only one instance of the app runs at a time. If a second instance is launched, it quits immediately and the first instance is focused.
+
+```typescript
+new SingleInstance()
+```
+
+#### PrivilegedSchemes
+
+Registers custom URL schemes as privileged (secure, standard, with Fetch API support). Runs in `beforeReady`. Pair with `StaticFileDir` to serve local files via a custom scheme.
+
+```typescript
+new PrivilegedSchemes(['app'])
+
+// Multiple schemes
+new PrivilegedSchemes(['app', 'media'])
+```
+
+#### StaticFileDir
+
+Registers a custom scheme to serve static files from a local directory. Runs in `afterReady`.
+
+```typescript
+new StaticFileDir('app', path.join(__dirname, '../renderer'))
+
+// A separate scheme for media assets
+new StaticFileDir('media', path.join(__dirname, '../assets'))
+```
+
+#### TouchEvents
+
+Enables touch event support via Chromium's `--touch-events` command-line switch.
+
+```typescript
+new TouchEvents()
+```
+
+#### Heartbeat
+
+Sends periodic HTTP HEAD requests to a URL for uptime monitoring. Only runs when packaged by default.
+
+```typescript
+import { Heartbeat } from '@dimensional-innovations/electron-background';
+
+new Heartbeat({ url: 'https://your-monitor.example.com/ping', pollInterval: 30_000 })
+```
+
+#### BetterStackHeartbeat
+
+Sends periodic heartbeats to [BetterStack](https://betterstack.com) uptime monitoring. Only runs when packaged by default.
+
+```typescript
+import { BetterStackHeartbeat } from '@dimensional-innovations/electron-background';
+
+new BetterStackHeartbeat({ heartbeatApiKey: 'your-api-key' })
+
+// Custom poll interval (default is 30 seconds)
+new BetterStackHeartbeat({ heartbeatApiKey: 'your-api-key', pollInterval: 60_000 })
+```
+
+---
+
+## Custom Plugins
+
+Implement the `InitPlugin` interface and define whichever lifecycle methods your plugin needs. Omitting a method means that phase is skipped for your plugin.
+
+```typescript
+import {
+  InitPlugin,
+  NonBrowserWindowInitContext,
+  BrowserWindowInitContext,
+} from '@dimensional-innovations/electron-background';
+
+class MyPlugin implements InitPlugin {
+  async afterReady({ log }: NonBrowserWindowInitContext): Promise<void> {
+    log.info('App is ready');
+  }
+
+  async afterLoad({ browserWindow, log }: BrowserWindowInitContext): Promise<void> {
+    log.info('Window loaded:', browserWindow.id);
+  }
+}
+```
+
+Pass the plugin directly in the `plugins` array:
+
+```typescript
+init({
+  windows: [...],
+  plugins: [new MyPlugin()],
+});
+```
+
+---
+
+### Example: Window Spanning Multiple Displays
+
+For setups where a single window must stretch across several displays, use a custom plugin to compute the combined bounds of all displays and apply them via `setBounds` in `afterLoad`. `FullScreenBrowserWindow` is used as the base window because it removes the frame and disables user resizing and movement — the plugin then overrides the bounds to cover all displays.
+
+```typescript
+import { screen } from 'electron';
+import path from 'path';
+import {
+  init,
+  InitPlugin,
+  BrowserWindowInitContext,
+  FullScreenBrowserWindow,
+  PrivilegedSchemes,
+  StaticFileDir,
+} from '@dimensional-innovations/electron-background';
+
+class SpanAllDisplays implements InitPlugin {
+  async afterLoad({ browserWindow }: BrowserWindowInitContext): Promise<void> {
+    const displays = screen.getAllDisplays();
+
+    const left   = Math.min(...displays.map(d => d.bounds.x));
+    const top    = Math.min(...displays.map(d => d.bounds.y));
+    const right  = Math.max(...displays.map(d => d.bounds.x + d.bounds.width));
+    const bottom = Math.max(...displays.map(d => d.bounds.y + d.bounds.height));
+
+    browserWindow.setBounds({
+      x: left,
+      y: top,
+      width: right - left,
+      height: bottom - top,
+    });
+  }
+}
+
+init({
+  windows: [
+    () => new FullScreenBrowserWindow({ appUrl: 'app://index.html' }),
+  ],
+  plugins: [
+    new PrivilegedSchemes(['app']),
+    new StaticFileDir('app', path.join(__dirname, '../renderer')),
+    new SpanAllDisplays(),
+  ],
+});
+```
+
+---
 
 ## API Reference
-For the complete API exported by this package, see API.md
+
+For the complete API exported by this package, see [API.md](./API.md).

package/dist/InitContext.d.ts

@@ -0,0 +1,40 @@
+import { AppBrowserWindow } from "./windows/AppBrowserWindow";
+/**
+ * The context object passed to each plugin during the init process.
+ */
+export declare class InitContext<T = unknown> {
+    /**
+     * The log instance. This should be used over `console` in plugin implementations.
+     */
+    log: Pick<Console, 'error' | 'warn' | 'info' | 'debug'>;
+    config?: T | undefined;
+    /**
+     * The browser window that the app is loaded into. This is available in the context
+     * in the `beforeLoad` and `afterLoad` methods.
+     */
+    browserWindow?: AppBrowserWindow | undefined;
+    constructor(
+    /**
+     * The log instance. This should be used over `console` in plugin implementations.
+     */
+    log: Pick<Console, 'error' | 'warn' | 'info' | 'debug'>, config?: T | undefined, 
+    /**
+     * The browser window that the app is loaded into. This is available in the context
+     * in the `beforeLoad` and `afterLoad` methods.
+     */
+    browserWindow?: AppBrowserWindow | undefined);
+}
+/**
+ * Represents the InitContext during the beforeReady phase.
+ */
+export type BeforeReadyInitContext<T> = Omit<InitContext<T>, 'config' | 'browserWindow'>;
+/**
+ * Represents the InitContext before the BrowserWindow has been set. Used in the
+ * "beforeReady" and "afterReady" methods.
+ */
+export type NonBrowserWindowInitContext<T> = Omit<InitContext<T>, 'config' | 'browserWindow'> & Required<Pick<InitContext<T>, 'config'>>;
+/**
+ * Represents the InitContext after the BrowserWindow has been set. Used in the
+ * "beforeLoad" and "afterLoad" methods.
+ */
+export type BrowserWindowInitContext<T> = Omit<InitContext<T>, 'config' | 'browserWindow'> & Required<Pick<InitContext<T>, 'config' | 'browserWindow'>>;

package/dist/InitContext.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InitContext = void 0;
+/**
+ * The context object passed to each plugin during the init process.
+ */
+class InitContext {
+    constructor(
+    /**
+     * The log instance. This should be used over `console` in plugin implementations.
+     */
+    log, config, 
+    /**
+     * The browser window that the app is loaded into. This is available in the context
+     * in the `beforeLoad` and `afterLoad` methods.
+     */
+    browserWindow) {
+        this.log = log;
+        this.config = config;
+        this.browserWindow = browserWindow;
+    }
+}
+exports.InitContext = InitContext;

package/dist/InitPlugin.d.ts

@@ -0,0 +1,39 @@
+import { BeforeReadyInitContext, NonBrowserWindowInitContext, BrowserWindowInitContext } from "./InitContext";
+/**
+ * A plugin is used to execute logic at various stages during the init process.
+ *
+ * Implementations can define one or more of the optional methods to customize
+ * application instance.
+ */
+export interface InitPlugin<T = unknown> {
+    /**
+     * beforeReady is executed before the `app.whenReady()` promise resolves.
+     * beforeReady method must be synchronous so that all methods complete before the
+     * app.whenReady promise resolves.
+     *
+     * @param context - The current InitContext instance.
+     */
+    beforeReady?(context: BeforeReadyInitContext<T>): false;
+    /**
+     * afterReady is executed after the `app.whenReady()` promise resolves, but before the
+     * BrowserWindow is created.
+     *
+     * @param context - The current InitContext instance.
+     */
+    afterReady?(context: NonBrowserWindowInitContext<T>): Promise<void>;
+    /**
+     * beforeLoad is executed after the browserWindow is created, but before the application
+     * has been loaded into the window. This runs for each BrowserWindow created during init
+     * process.
+     *
+     * @param context - The current InitContext instance.
+     */
+    beforeLoad?(context: BrowserWindowInitContext<T>): Promise<void>;
+    /**
+     * afterLoad is executed after the application has been loaded into the browserWindow.
+     * This runs for each BrowserWindow created during the init process.
+     *
+     * @param context - The current InitContext instance.
+     */
+    afterLoad?(context: BrowserWindowInitContext<T>): Promise<void>;
+}

package/dist/InitPlugin.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -1,9 +1,13 @@
-export * from './AutoUpdater';
-export * from './BrowserWindow';
-export * from './DevTools';
-export * from './NodeHeartbeat';
-export * from './PrivilegedSchemes';
-export * from './SingleInstance';
-export * from './StaticFileDir';
-export * from './TouchEvents';
+export * from './plugins/AutoUpdater';
+export * from './plugins/DevTools';
+export * from './plugins/NodeHeartbeat';
+export * from './plugins/PrivilegedSchemes';
+export * from './plugins/SingleInstance';
+export * from './plugins/StaticFileDir';
+export * from './plugins/TouchEvents';
+export * from './windows/AppBrowserWindow';
+export * from './windows/FullScreenBrowserWindow';
+export * from './windows/KioskBrowserWindow';
 export * from './init';
+export * from './InitContext';
+export * from './InitPlugin';

package/dist/index.js

@@ -14,12 +14,16 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./AutoUpdater"), exports);
-__exportStar(require("./BrowserWindow"), exports);
-__exportStar(require("./DevTools"), exports);
-__exportStar(require("./NodeHeartbeat"), exports);
-__exportStar(require("./PrivilegedSchemes"), exports);
-__exportStar(require("./SingleInstance"), exports);
-__exportStar(require("./StaticFileDir"), exports);
-__exportStar(require("./TouchEvents"), exports);
+__exportStar(require("./plugins/AutoUpdater"), exports);
+__exportStar(require("./plugins/DevTools"), exports);
+__exportStar(require("./plugins/NodeHeartbeat"), exports);
+__exportStar(require("./plugins/PrivilegedSchemes"), exports);
+__exportStar(require("./plugins/SingleInstance"), exports);
+__exportStar(require("./plugins/StaticFileDir"), exports);
+__exportStar(require("./plugins/TouchEvents"), exports);
+__exportStar(require("./windows/AppBrowserWindow"), exports);
+__exportStar(require("./windows/FullScreenBrowserWindow"), exports);
+__exportStar(require("./windows/KioskBrowserWindow"), exports);
 __exportStar(require("./init"), exports);
+__exportStar(require("./InitContext"), exports);
+__exportStar(require("./InitPlugin"), exports);