switch-framework-electron 0.2.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Switcherfaiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# switch-framework-electron
+
+Electron helpers for [Switch Framework](https://github.com/Switcherfaiz/switch-framework) desktop apps — child server forking, dynamic ports, IPC, splash bootstrap, and window controls.
+
+## Install
+
+```bash
+npm install switch-framework-electron switch-framework switch-framework-backend
+npm install electron --save-dev
+```
+
+Scaffold a full app with the CLI:
+
+```bash
+npx create-switch-framework-app my-app --app-type electron
+```
+
+## Usage
+
+**`electron/servers.js`** — declare child processes:
+
+```javascript
+module.exports = [
+  { name: 'app', entry: 'server.js' },
+  { name: 'worker', entry: 'worker-server.js' },
+];
+```
+
+**`electron/main.js`** — bootstrap:
+
+```javascript
+const path = require('node:path');
+const { bootstrapElectronApp } = require('switch-framework-electron');
+const servers = require('./servers.js');
+
+bootstrapElectronApp({
+  servers,
+  preloadPath: path.join(__dirname, 'preload.js'),
+  splashHtmlPath: path.join(__dirname, 'splash.html'),
+  appRoot: path.join(__dirname, '..'),
+  cwd: path.join(__dirname, '..'),
+});
+```
+
+Each **`entry`** file is a normal Node script that starts an HTTP server (via `switch-framework-backend` or raw `http.createServer`). The package assigns a free localhost port and reports it over IPC.
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `bootstrapElectronApp(options)` | Splash → fork servers → open main window |
+| `startServers(list, session, opts)` | Fork all entries from `servers.js` |
+| `onServerReady(cb)` / `whenServerReady()` | Called when every server reported a port |
+| `registerWindowIpc(win)` | Minimize / maximize / close for frameless windows |
+| `createLocalSession()` | Random token for local auth cookie |
+| `childEntry` | Internal fork script path |
+
+## Docs
+
+[Desktop Server](https://github.com/Switcherfaiz/switch-framework-docs) · [Multiple child servers](https://github.com/Switcherfaiz/switch-framework-docs) · [Package reference](https://github.com/Switcherfaiz/switch-framework-docs)
+
+## License
+
+MIT © Faiz Ahmad Ally (Switcherfaiz)

package/child.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const path = require('node:path');
+const http = require('http');
+const { SERVER_READY_MESSAGE } = require('./lib/messages.js');
+const {
+  SERVER_CHILD_FLAG,
+  APP_ROOT_ENV,
+} = require('./lib/constants.js');
+
+if (process.env[SERVER_CHILD_FLAG] !== '1') {
+  throw new Error('switch-framework-electron/child.js must run as a forked server child');
+}
+
+const origListen = http.Server.prototype.listen;
+http.Server.prototype.listen = function patchedListen() {
+  const port = process.env.PORT === undefined ? 0 : Number(process.env.PORT);
+  const host = process.env.SWITCH_BIND_HOST || '127.0.0.1';
+  this.once('listening', () => {
+    const addr = this.address();
+    const info = {
+      type: SERVER_READY_MESSAGE,
+      name: process.env.SWITCH_SERVER_NAME || 'app',
+      port: typeof addr === 'object' && addr ? addr.port : port,
+      host: typeof addr === 'object' && addr ? addr.address : host,
+    };
+    console.log(`[switch-framework-electron:${info.name}] http://${info.host}:${info.port}`);
+    if (typeof process.send === 'function') process.send(info);
+  });
+  return origListen.call(this, Number.isFinite(port) ? port : 0, host);
+};
+
+const appRoot = process.env[APP_ROOT_ENV];
+const entry = process.env.SWITCH_SERVER_ENTRY || 'server.js';
+require(path.join(appRoot, entry));

package/index.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const pkg = require('./package.json');
+
+const ipc = require('./lib/ipc.js');
+const session = require('./lib/session.js');
+const servers = require('./lib/servers.js');
+const bootstrap = require('./lib/bootstrap.js');
+const paths = require('./lib/paths.js');
+const messages = require('./lib/messages.js');
+const constants = require('./lib/constants.js');
+
+const VERSION = pkg.version;
+
+module.exports = {
+  VERSION,
+  ...ipc,
+  ...session,
+  ...servers,
+  ...bootstrap,
+  ...paths,
+  ...messages,
+  ...constants,
+  childEntry: require('node:path').join(__dirname, 'child.js'),
+};

package/lib/bootstrap.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const path = require('node:path');
+const { app, BrowserWindow } = require('electron');
+const { createLocalSession } = require('./session.js');
+const { onServerReady, registerWindowIpc } = require('./ipc.js');
+const { startServers, stopServerProcess } = require('./servers.js');
+
+async function attachLocalAuthCookie(win, host, port, token) {
+  if (!token || !win) return;
+  const url = `http://${host}:${port}/`;
+  try {
+    await win.webContents.session.cookies.set({
+      url,
+      name: 'switch-local-auth',
+      value: token,
+      httpOnly: true,
+      path: '/',
+    });
+  } catch (err) {
+    console.error('[switch-framework-electron] Failed to set local auth cookie:', err);
+  }
+}
+
+function createSplashWindow(splashHtmlPath, bounds = { width: 1200, height: 800 }) {
+  const splash = new BrowserWindow({
+    ...bounds,
+    center: true,
+    frame: false,
+    backgroundColor: '#f5f5f5',
+    show: false,
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+    },
+  });
+
+  splash.loadFile(splashHtmlPath);
+  splash.once('ready-to-show', () => splash.show());
+  return splash;
+}
+
+function createMainWindow({
+  bounds,
+  host,
+  port,
+  token,
+  preloadPath,
+  backgroundColor = '#f5f5f5',
+  frame = false,
+  webPreferences = {},
+  onMainWindowCreated,
+}) {
+  return new Promise((resolve) => {
+    process.env.SWITCH_WINDOW_HOST = host;
+    process.env.SWITCH_WINDOW_PORT = String(port);
+
+    const mainWindow = new BrowserWindow({
+      ...bounds,
+      frame,
+      backgroundColor,
+      show: false,
+      webPreferences: {
+        preload: preloadPath,
+        nodeIntegration: false,
+        contextIsolation: true,
+        ...webPreferences,
+      },
+    });
+
+    if (typeof onMainWindowCreated === 'function') {
+      onMainWindowCreated(mainWindow);
+    }
+
+    registerWindowIpc(mainWindow);
+
+    mainWindow.on('closed', () => {
+      mainWindow._swClosed = true;
+    });
+
+    const appUrl = `http://${host}:${port}/`;
+
+    mainWindow.webContents.on('did-fail-load', (_event, _code, description) => {
+      console.error('[switch-framework-electron] Page failed to load:', description);
+      setTimeout(() => {
+        if (!mainWindow.isDestroyed()) mainWindow.loadURL(appUrl);
+      }, 750);
+    });
+
+    mainWindow.once('ready-to-show', () => resolve(mainWindow));
+
+    attachLocalAuthCookie(mainWindow, host, port, token).then(() => {
+      mainWindow.loadURL(appUrl);
+    });
+  });
+}
+
+function bootstrapElectronApp(options = {}) {
+  const {
+    servers = [{ name: 'app', entry: 'server.js' }],
+    preloadPath,
+    splashHtmlPath,
+    appRoot,
+    cwd,
+    windowBounds = { width: 1200, height: 800 },
+    webPreferences = {},
+    onMainWindowCreated,
+    onReady,
+  } = options;
+
+  if (!preloadPath) throw new Error('bootstrapElectronApp requires preloadPath');
+  if (!splashHtmlPath) throw new Error('bootstrapElectronApp requires splashHtmlPath');
+
+  let splashWindow = null;
+  let mainWindow = null;
+  let localSession = null;
+  let bootstrapping = false;
+
+  async function openMainWindow(ports) {
+    if (!splashWindow || splashWindow.isDestroyed()) return;
+
+    const appServer = ports.app || Object.values(ports)[0];
+    if (!appServer?.port) throw new Error('App server did not report a port');
+
+    const host = appServer.host || '127.0.0.1';
+    const bounds = splashWindow.getBounds();
+
+    mainWindow = await createMainWindow({
+      bounds,
+      host,
+      port: appServer.port,
+      token: localSession?.token,
+      preloadPath,
+      webPreferences,
+      onMainWindowCreated,
+    });
+
+    if (typeof onReady === 'function') {
+      await onReady({ ports, mainWindow, splashWindow });
+    }
+
+    if (splashWindow && !splashWindow.isDestroyed()) splashWindow.close();
+    if (mainWindow && !mainWindow.isDestroyed()) mainWindow.show();
+  }
+
+  function bootstrap() {
+    if (bootstrapping) return;
+    bootstrapping = true;
+
+    localSession = createLocalSession();
+    splashWindow = createSplashWindow(splashHtmlPath, windowBounds);
+    startServers(servers, localSession, { appRoot, cwd });
+
+    onServerReady((ports) => {
+      openMainWindow(ports)
+        .catch((err) => {
+          console.error('[switch-framework-electron] Failed to open main window:', err);
+          if (splashWindow && !splashWindow.isDestroyed()) splashWindow.close();
+          if (!mainWindow) app.quit();
+        })
+        .finally(() => {
+          bootstrapping = false;
+        });
+    });
+  }
+
+  app.on('before-quit', () => stopServerProcess());
+
+  app.whenReady().then(() => {
+    bootstrap();
+    app.on('activate', () => {
+      if (BrowserWindow.getAllWindows().length === 0) bootstrap();
+    });
+  });
+
+  app.on('window-all-closed', () => {
+    if (process.platform !== 'darwin') app.quit();
+  });
+}
+
+module.exports = {
+  bootstrapElectronApp,
+  createSplashWindow,
+  createMainWindow,
+  attachLocalAuthCookie,
+};

package/lib/constants.js

@@ -0,0 +1,8 @@
+'use strict';
+
+module.exports = {
+  SERVER_CHILD_FLAG: 'SWITCH_SERVER_CHILD',
+  APP_ROOT_ENV: 'SWITCH_APP_ROOT',
+  USER_DATA_ENV: 'SWITCH_USER_DATA',
+  IS_PACKAGED_ENV: 'SWITCH_IS_PACKAGED',
+};

package/lib/ipc.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const { ipcMain } = require('electron');
+const { SERVER_READY_MESSAGE } = require('./messages.js');
+
+const serverPorts = {};
+const pendingServers = new Set();
+const readyListeners = [];
+let allReady = false;
+
+function expectServers(names = []) {
+  pendingServers.clear();
+  names.forEach((name) => pendingServers.add(name));
+  allReady = pendingServers.size === 0;
+}
+
+function notifyAllReady() {
+  allReady = true;
+  readyListeners.splice(0).forEach((listener) => listener({ ...serverPorts }));
+}
+
+function onServerInfo(info) {
+  if (!info || info.type !== SERVER_READY_MESSAGE) return;
+  if (info.name) {
+    serverPorts[info.name] = { port: info.port, host: info.host };
+    pendingServers.delete(info.name);
+  }
+  if (pendingServers.size === 0) notifyAllReady();
+}
+
+function onServerReady(listener) {
+  if (allReady) {
+    listener({ ...serverPorts });
+    return;
+  }
+  readyListeners.push(listener);
+}
+
+function whenServerReady() {
+  return new Promise((resolve) => onServerReady(resolve));
+}
+
+function resetServerReady() {
+  allReady = false;
+  Object.keys(serverPorts).forEach((key) => delete serverPorts[key]);
+}
+
+function registerServerIpc(serverProcess) {
+  serverProcess.on('message', onServerInfo);
+}
+
+function registerWindowIpc(mainWindow) {
+  try { ipcMain.removeHandler('window:is-maximized'); } catch (_) {}
+  ipcMain.removeAllListeners('window:minimize');
+  ipcMain.removeAllListeners('window:maximize');
+  ipcMain.removeAllListeners('window:close');
+
+  ipcMain.on('window:minimize', () => {
+    mainWindow?.minimize();
+  });
+
+  ipcMain.on('window:maximize', () => {
+    if (!mainWindow) return;
+    if (mainWindow.isMaximized()) mainWindow.unmaximize();
+    else mainWindow.maximize();
+  });
+
+  ipcMain.on('window:close', () => {
+    mainWindow?.close();
+  });
+
+  ipcMain.handle('window:is-maximized', () => {
+    return mainWindow?.isMaximized?.() ?? false;
+  });
+}
+
+function getServerPorts() {
+  return { ...serverPorts };
+}
+
+module.exports = {
+  SERVER_READY_MESSAGE,
+  expectServers,
+  registerServerIpc,
+  registerWindowIpc,
+  onServerReady,
+  whenServerReady,
+  resetServerReady,
+  getServerPorts,
+};

package/lib/messages.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const SERVER_READY_MESSAGE = 'ready';
+
+module.exports = { SERVER_READY_MESSAGE };

package/lib/paths.js

@@ -0,0 +1,30 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+function getAppRoot(appRootOverride) {
+  if (appRootOverride) return appRootOverride;
+  const { app } = require('electron');
+  return app.isPackaged ? app.getAppPath() : process.cwd();
+}
+
+function configurePackagedPaths() {
+  const { app } = require('electron');
+  if (!app.isPackaged) return;
+
+  const esbuildBinary = path.join(
+    process.resourcesPath,
+    'app.asar.unpacked',
+    'node_modules',
+    '@esbuild',
+    `${process.platform}-${process.arch}`,
+    process.platform === 'win32' ? 'esbuild.exe' : 'bin/esbuild',
+  );
+
+  if (fs.existsSync(esbuildBinary)) {
+    process.env.ESBUILD_BINARY_PATH = esbuildBinary;
+  }
+}
+
+module.exports = { getAppRoot, configurePackagedPaths };

package/lib/servers.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const path = require('node:path');
+const { fork } = require('node:child_process');
+const {
+  SERVER_CHILD_FLAG,
+  APP_ROOT_ENV,
+  USER_DATA_ENV,
+  IS_PACKAGED_ENV,
+} = require('./constants.js');
+const { registerServerIpc, expectServers } = require('./ipc.js');
+const { configurePackagedPaths, getAppRoot } = require('./paths.js');
+
+const processes = new Map();
+
+function getChildScriptPath() {
+  return path.join(__dirname, '..', 'child.js');
+}
+
+function stopServerProcess(name) {
+  if (name) {
+    const child = processes.get(name);
+    if (child && !child.killed) child.kill();
+    processes.delete(name);
+    return;
+  }
+  for (const [key, child] of processes) {
+    if (child && !child.killed) child.kill();
+    processes.delete(key);
+  }
+}
+
+function startServerProcess(spec = {}, session = {}, options = {}) {
+  const name = spec.name || 'app';
+  if (processes.has(name)) return processes.get(name);
+
+  const { app } = require('electron');
+  configurePackagedPaths();
+
+  const childPath = getChildScriptPath();
+  const forkCwd = app.isPackaged ? process.resourcesPath : (options.cwd || process.cwd());
+  const appRoot = getAppRoot(options.appRoot);
+  const userDataPath = app.getPath('userData');
+
+  const child = fork(childPath, [], {
+    cwd: forkCwd,
+    env: {
+      ...process.env,
+      ELECTRON_RUN_AS_NODE: '1',
+      [SERVER_CHILD_FLAG]: '1',
+      [APP_ROOT_ENV]: appRoot,
+      [USER_DATA_ENV]: userDataPath,
+      [IS_PACKAGED_ENV]: app.isPackaged ? '1' : '0',
+      SWITCH_SERVER_NAME: name,
+      SWITCH_SERVER_ENTRY: spec.entry || 'server.js',
+      PORT: '0',
+      SWITCH_BIND_HOST: '127.0.0.1',
+      SWITCH_LOCAL_AUTH_TOKEN: session.token || '',
+      ...(spec.env || {}),
+    },
+    stdio: ['inherit', 'inherit', 'inherit', 'ipc'],
+  });
+
+  registerServerIpc(child);
+
+  child.on('error', (err) => {
+    console.error(`[switch-framework-electron:${name}] Process error:`, err);
+  });
+
+  child.on('exit', (code, signal) => {
+    if (code !== 0 && code !== null) {
+      console.error(`[switch-framework-electron:${name}] Process exited:`, { code, signal });
+    }
+    processes.delete(name);
+  });
+
+  processes.set(name, child);
+  return child;
+}
+
+function startServers(serverList = [], session = {}, options = {}) {
+  const list = Array.isArray(serverList) ? serverList : [serverList];
+  expectServers(list.map((item) => item.name || 'app'));
+  return list.map((item) => startServerProcess(item, session, options));
+}
+
+module.exports = {
+  startServerProcess,
+  startServers,
+  stopServerProcess,
+  getChildScriptPath,
+};

package/lib/session.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+function createLocalSession() {
+  return {
+    token: crypto.randomBytes(32).toString('hex'),
+  };
+}
+
+module.exports = { createLocalSession };

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "switch-framework-electron",
+  "version": "0.2.9",
+  "description": "Electron desktop helpers for the Switch Framework ecosystem — child servers, dynamic ports, IPC, splash bootstrap, and window controls for building Electron apps with switch-framework and switch-framework-backend",
+  "author": "Switcherfaiz",
+  "github": "https://github.com/Switcherfaiz/switch-framework-electron",
+  "main": "./index.js",
+  "type": "commonjs",
+  "files": [
+    "index.js",
+    "child.js",
+    "lib/**/*.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "electron": ">=28"
+  },
+  "license": "MIT",
+  "keywords": [
+    "switch-framework",
+    "electron",
+    "desktop"
+  ]
+}