CoAkka Runtime Connector For Electron

This is the Electron connector in the polyglot, multi-language, multi-platform CoAkka Runtime ecosystem. CoAkka is not an Electron-only runtime: this package keeps native runtime ownership in the main process while preserving the same target, request/reply, bounded-admission, and deadletter contract used by Node.js, the JVM, Python, Go, C#, Rust, Swift, and other connector lanes.

Kubernetes is supported but not required. Use the public Ecosystem Overview and Compatibility Matrix to select an exact package and native platform tuple. Start with the CoAkka Documentation for concepts, integration paths, operations, and runnable samples.

New To CoAkka

CoAkka is a native-backed runtime and logger toolkit for application-owned work. It helps an app route work by target name, handle request/reply, deadletters, bounded queues, diagnostics, and native-backed logging without turning every internal boundary into another hand-written HTTP endpoint.

Use these public repositories to orient first:

| Repository | Use it for | Link | | --- | --- | --- | | coakka-samples | Runnable examples and code you can inspect first. | https://github.com/phuong-tran/coakka-samples | | coakka-publish | Released packages, native archives, manifests, checksums, compatibility matrix, and release notes. | https://github.com/phuong-tran/coakka-publish |

Run the matching sample:

git clone https://github.com/phuong-tran/coakka-samples.git
cd coakka-samples
bash run.sh runtime electron basic

No-checkout npm smoke: https://github.com/phuong-tran/coakka-samples/blob/main/docs/first-npm-smoke.md

Samples docs directory: https://github.com/phuong-tran/coakka-samples/tree/main/docs

That smoke explains the runtime mental model first: keep real HTTP or IPC at the app edge, but replace fake backend HTTP used only for work owned by the same app or team with a CoAkka target and explicit reply/deadletter behavior.

The boundary is intentionally strict:

• renderer JavaScript sends an intent through ipcRenderer.invoke
• preload exposes only a small coakka.intent(...) API
• the Electron main process owns ElectronRuntimeIntentBridge
• the main process converts the intent into runtime delivery and projects the result back to the renderer

Renderer code does not import the runtime connector, does not know runtime envelopes, and does not own native runtime lifecycle.

The main-process options can forward the shared connectionStrategy and security startup specs. Capability/config/security getters and atomic apply results are exposed on ElectronRuntimeIntentBridge; renderer/preload code still never receives credential material. See Connection Strategies, TLS and mTLS, and Troubleshooting.

Main Process

import { ipcMain } from "electron";
import {
  ElectronRuntimeIntentBridge,
  registerElectronIntentIpcHandler,
} from "coakka-v2-connector-electron";

const target = "samples.electron.intent.echo";
const bridge = ElectronRuntimeIntentBridge.start({
  systemName: "electron-app",
  nodeId: "electron-app-main",
  defaultTarget: target,
});

bridge.registerJsonIntentHandler(target, async (intent) => ({
  handledBy: "electron-main",
  echo: intent.payload,
}));

registerElectronIntentIpcHandler(ipcMain, bridge);

Preload

const { contextBridge, ipcRenderer } = require("electron");
const { createCoAkkaPreloadApi } = require("coakka-v2-connector-electron/preload");

contextBridge.exposeInMainWorld("coakka", createCoAkkaPreloadApi(ipcRenderer));

Renderer

const result = await window.coakka.intent({
  intentId: "intent-1",
  source: "electron-renderer",
  target: "samples.electron.intent.echo",
  operation: "echo",
  payload: { message: "hello-electron-runtime" },
  payloadIdentity: {
    messageType: "samples.electron.intent.echo.request.v1",
    payloadSchemaVersion: 1,
    payloadFormat: "json",
  },
  timeoutMs: 2000,
});

Smoke

npm run build
bash scripts/smoke-packaged-package.sh

The packaged smoke installs the generated package into a disposable Electron app, loads a hidden renderer window, sends one renderer intent through preload and IPC, and verifies that the main process handles it through the runtime host exposed by its packaged Node connector dependency.

Package metadata records the exact native generation, release channel, and supported platform tuple. Contact: [email protected].