Capacitor Community Electron Platform

To support Capacitor's addListener and removeListener methods in an Electron plugin, your plugin class must extend the EventEmitter class from the events Node.js module. This allows the Electron runtime to expose event-handling capabilities to the web layer.

Implementation

Extend EventEmitter and use this.emit(eventName, data) to trigger events.

Client Usage

Access the plugin via CapacitorCustomPlatform.plugins to attach listeners.

// Plugin Implementation
import { EventEmitter } from 'events';

export default class MyPlugin extends EventEmitter {
  constructor() {
    super();
    setInterval(() => {
      this.emit('my-event', 'You successfully listened to the 10sec event!');     
    }, 10_000);
  }
}

// Client Code
const id = CapacitorCustomPlatform.plugins.MyPlugin.addListener('my-event', console.log);

// To stop listening:
CapacitorCustomPlatform.plugins.MyPlugin.removeListener(id);

To extend a Capacitor V3 compatible plugin with Electron support, follow these steps to set up the directory structure, build configuration, and registration:

1. Directory Structure

Create an electron folder in the root of your plugin, containing a src sub-folder. Place your implementation in electron/src/index.ts.

2. Configuration Files

Create the following files inside the electron folder:

• .gitignore: Include dist.
• .npmignore: Include src.
• rollup.config.js: Configures the build output to electron/dist/plugin.js in CommonJS format.
• tsconfig.json: Configures TypeScript compilation with outDir set to build.

3. Update Root package.json

Modify your plugin's root package.json with these changes:

• capacitor object: Add the electron platform.
• files array: Include electron/ to ensure the build artifacts are published.
• scripts: Add a build-electron script and update the main build script to include the electron build step.

4. Register the Plugin

In your plugin's main entry point (<root>/src/index.ts), register the Electron implementation using CapacitorCustomPlatform:

const Dialog = registerPlugin<DialogPlugin>('Dialog', {
  web: () => import('./web').then(m => new m.DialogWeb()),
  electron: () => (window as any).CapacitorCustomPlatform.plugins.DialogElectron
});

5. Build and Sync

Run npm run build to compile the plugin. Once published, use npx cap sync (or copy/update) in your Capacitor app to include the new Electron platform support.

// Example package.json modifications
{
  "capacitor": {
    "ios": { "src": "ios" },
    "android": { "src": "android" },
    "electron": { "src": "electron" }
  },
  "files": [
    "electron/"
  ],
  "scripts": {
    "build-electron": "tsc --project electron/tsconfig.json && rollup -c electron/rollup.config.js && rimraf ./electron/build",
    "build": "npm run clean && npm run docgen && tsc && rollup -c rollup.config.js && npm run build-electron"
  }
}

To add Electron support to your existing Capacitor project, the add command (implemented via doAdd) automates the following setup steps:

1. Creates the electron directory: A new directory named electron is created in your project root.
2. Extracts the template: The Electron platform template is extracted into the electron directory.
3. Copies Capacitor configuration: Your project's capacitor.config file (searched in order: .ts, .js, or .json) is copied into the electron directory.
4. Configures package.json: The name field in the new electron/package.json is updated to match your project's appName from your Capacitor configuration. If your root package.json contains a repository field, it is also copied to the Electron platform's package.json.
5. Installs dependencies: Runs npm i inside the electron directory to install necessary modules.

Note: This process will fail if the electron directory already exists.

# While the specific CLI command name is not explicitly exported in this file, 
# it is the implementation for the 'add' command used to initialize the platform.
npx cap add electron

When instantiating ElectronCapacitorApp, you can customize the application behavior via the CapacitorElectronConfig and optional menu templates:

• capacitorFileConfig.electron.splashScreenEnabled: If true, shows a splash screen while the web app loads.
• capacitorFileConfig.electron.splashScreenImageName: The filename of the splash image (defaults to splash.png) located in the assets folder.
• capacitorFileConfig.electron.trayIconAndMenuEnabled: If true, enables a system tray icon.
• capacitorFileConfig.electron.hideMainWindowOnLaunch: If true, the main window remains hidden until the splash screen is dismissed.
• capacitorFileConfig.electron.backgroundColor: Sets the background color of the main window.
• capacitorFileConfig.electron.customUrlScheme: Defines the custom URL scheme used for loading the web app (defaults to capacitor-electron).
• trayMenuTemplate: An array of MenuItemConstructorOptions or MenuItem objects for the system tray context menu.
• appMenuBarMenuTemplate: An array of MenuItemConstructorOptions or MenuItem objects for the application menu bar.

The electron-builder.config.json file defines how your Electron application is packaged, distributed, and installed. Key configuration areas include application identity, file inclusion, publishing providers, and platform-specific installer settings (NSIS for Windows, DMG for macOS).

Note that the values in the template (like com.yourdoamnin.yourapp) are placeholders and must be updated to match your specific application identity.

{
  "appId": "com.yourdoamnin.yourapp",
  "directories": {
    "buildResources": "resources"
  },
  "files": [
    "assets/**/*",
    "build/**/*",
    "capacitor.config.*",
    "app/**/*"
  ],
  "publish": {
    "provider": "github"
  },
  "nsis": {
    "allowElevation": true,
    "oneClick": false,
    "allowToChangeInstallationDirectory": true
  },
  "win": {
    "target": "nsis",
    "icon": "assets/appIcon.ico"
  },
  "mac": {
    "category": "your.app.category.type",
    "target": "dmg"
  }
}