Anhang: Electron-Kernwissen zusammenfassung

Dieser Anhang enthält eine schnelle Referenz für Electron-Entwickler.

1. Kernmodule-Kurzreferenz

Nach Verwendungshäufigkeit sortiert

Hauptprozess-Module

Modul	Häufigkeit	Wichtige Methoden
app	⭐⭐⭐⭐⭐	whenReady(), quit(), getPath()
BrowserWindow	⭐⭐⭐⭐⭐	new BrowserWindow(), loadFile(), webContents
ipcMain	⭐⭐⭐⭐⭐	handle(), on(), removeHandler()
Menu	⭐⭐⭐⭐	setApplicationMenu(), buildFromTemplate()
Tray	⭐⭐⭐	new Tray(), setContextMenu()
dialog	⭐⭐⭐	showOpenDialog(), showSaveDialog()
Notification	⭐⭐	new Notification(), show()
shell	⭐⭐	openExternal(), openPath()
autoUpdater	⭐	checkForUpdates(), quitAndInstall()

Renderer-Prozess-Module (über Preload)

Modul	Häufigkeit	Wichtige Methoden
ipcRenderer	⭐⭐⭐⭐⭐	invoke(), send(), on()
contextBridge	⭐⭐⭐⭐⭐	exposeInMainWorld()
webFrame	⭐	setZoomFactor()

Modul-Verwendungsbeispiele

app

const { app } = require('electron');

// App bereit
app.whenReady().then(() => {
  console.log('App bereit!');
});

// App beenden
app.quit();

// App-Pfad abrufen
const appPath = app.getAppPath();
const userDataPath = app.getPath('userData');

// Ereignisse
app.on('ready', () => {});
app.on('window-all-closed', () => {});
app.on('activate', () => {});
app.on('before-quit', () => {});

BrowserWindow

const { BrowserWindow } = require('electron');

// Fenster erstellen
const win = new BrowserWindow({
  width: 800,
  height: 600,
  webPreferences: {
    preload: path.join(__dirname, 'preload.js'),
    contextIsolation: true,
    nodeIntegration: false
  }
});

// Seite laden
win.loadFile('index.html');
win.loadURL('https://example.com');

// Fenstersteuerung
win.show();
win.hide();
win.minimize();
win.maximize();
win.restore();
win.close();

// Ereignisse
win.on('closed', () => {});
win.on('ready-to-show', () => {});
win.webContents.on('did-finish-load', () => {});

ipcMain

const { ipcMain } = require('electron');

// Handle (Promise-basiert)
ipcMain.handle('get-data', async (event, params) => {
  const result = await fetchData(params);
  return result;  // Wird zum Renderer zurückgegeben
});

// On (einweg)
ipcMain.on('message', (event, data) => {
  console.log('Nachricht:', data);
  event.reply('reply-channel', 'Antwort');
});

// Handler entfernen
ipcMain.removeHandler('get-data');

2. Haupt- vs. Renderer-Prozess-Unterschiede

Vergleichstabelle

Aspekt	Hauptprozess	Renderer-Prozess
Laufzeitumgebung	Node.js	Chromium (Browser)
Zugriff auf Node.js	Ja (vollständig)	Nein (bei contextIsolation: true)
Fenstererstellung	Ja (BrowserWindow)	Nein
Applikationslebenszyklus	Ja (app-Modul)	Nein
Native APIs	Ja (vollständig)	Nein (nur über IPC)
UI-Rendering	Nein	Ja (HTML/CSS/JS)
IPC-Rolle	Empfängt/Sendet	Sendet/Empfängt
Dateisystemzugriff	Ja (fs-Modul)	Nein (nur über IPC)
Netzwerkanfragen	Ja (keine CORS-Beschränkungen)	Ja (CORS-Beschränkungen)
Mehrere Instanzen	Einfach (ein Hauptprozess)	Ja (ein Renderer pro Fenster)

Berechtigungsmatrix

Funktion	Hauptprozess	Renderer (mit nodeIntegration: true)	Renderer (mit contextIsolation: true)
require('fs')	✅	✅	❌ (nur über Preload)
new BrowserWindow()	✅	❌	❌
ipcMain.handle()	✅	❌	❌
ipcRenderer.send()	❌	✅	❌ (nur über Preload)
document.getElementById()	❌	✅	✅
fetch()	❌	✅	✅
new Notification()	✅	⚠️ (teils unterstützt)	❌ (über IPC)

3. IPC-Kommunikationsmethoden zusammenfassung

Methodenübersicht

Methode	Prozess	Richtung	Rückgabe	Verwendungszweck
ipcRenderer.send()	Renderer	→ Main	Keine	Einweg-Nachricht senden
ipcMain.on()	Main	←	Keine	Nachricht empfangen
event.reply()	Main	→ Renderer	Keine	Auf send() antworten
ipcRenderer.invoke()	Renderer	↔ Main	Promise	Zweiweg-Kommunikation (empfohlen)
ipcMain.handle()	Main	↔	Promise	Handler für invoke() definieren
ipcRenderer.on()	Renderer	←	Keine	Nachricht vom Hauptprozess empfangen
win.webContents.send()	Main	→ Renderer	Keine	An Renderer senden

Einweg-Kommunikation (Renderer → Main)

// preload.js
contextBridge.exposeInMainWorld('api', {
  sendMessage: (data) => ipcRenderer.send('message', data)
});

// main.js
ipcMain.on('message', (event, data) => {
  console.log('Nachricht empfangen:', data);
});

Einweg-Kommunikation (Main → Renderer)

// main.js
win.webContents.send('update', { status: 'ready' });

// preload.js
contextBridge.exposeInMainWorld('api', {
  onUpdate: (callback) => {
    ipcRenderer.on('update', (event, data) => callback(data));
  }
});

Zweiweg-Kommunikation (empfohlen)

// main.js
ipcMain.handle('get-user-data', async (event, userId) => {
  const userData = await fetchUserFromDatabase(userId);
  return userData;  // Wird zum Renderer zurückgegeben
});

// preload.js
contextBridge.exposeInMainWorld('api', {
  getUserData: (userId) => ipcRenderer.invoke('get-user-data', userId)
});

// renderer.js
async function loadUser() {
  try {
    const userData = await window.api.getUserData(123);
    console.log('Benutzerdaten:', userData);
  } catch (error) {
    console.error('Fehler:', error);
  }
}

4. Paketierungskonfigurationsvorlagen

package.json (Multi-Plattform)

{
  "name": "meine-electron-app",
  "version": "1.0.0",
  "description": "Meine Electron-App",
  "main": "main.js",
  "scripts": {
    "start": "electron .",
    "build:win": "electron-builder --win",
    "build:mac": "electron-builder --mac",
    "build:linux": "electron-builder --linux",
    "build:all": "electron-builder --mac --win --linux"
  },
  "build": {
    "appId": "com.beispiel.meineapp",
    "productName": "Meine App",
    "copyright": "Copyright © 2024",
    "directories": {
      "output": "dist"
    },
    "files": [
      "**/*",
      "!**/node_modules/*/{CHANGELOG.md,README.md,README,readme.md,readme}",
      "!**/node_modules/*/{test,__tests__,tests,powered-test,example,examples}",
      "!**/node_modules/*.d.ts"
    ],
    "win": {
      "target": "nsis",
      "icon": "assets/icon.ico",
      "publisherName": "Mein Unternehmen"
    },
    "mac": {
      "target": "dmg",
      "icon": "assets/icon.icns",
      "hardenedRuntime": true,
      "gatekeeperAssess": false,
      "entitlements": "build/entitlements.mac.plist",
      "entitlementsInherit": "build/entitlements.mac.plist"
    },
    "linux": {
      "target": "AppImage",
      "icon": "assets/icon.png",
      "category": "Utility"
    },
    "publish": [
      {
        "provider": "generic",
        "url": "https://update.example.com"
      }
    ]
  },
  "devDependencies": {
    "electron": "^31.0.0",
    "electron-builder": "^24.0.0"
  },
  "dependencies": {
    "electron-store": "^8.1.0"
  }
}

Windows NSIS-Konfiguration

{
  "build": {
    "nsis": {
      "oneClick": false,
      "allowElevation": true,
      "allowToChangeInstallationDirectory": true,
      "createDesktopShortcut": true,
      "createStartMenuShortcut": true,
      "shortcutName": "Meine App",
      "installerIcon": "assets/installer-icon.ico",
      "uninstallerIcon": "assets/uninstaller-icon.ico",
      "installerHeader": "assets/installer-header.bmp"
    }
  }
}

macOS DMG-Konfiguration

{
  "build": {
    "dmg": {
      "title": "Meine App ${version}",
      "icon": "assets/icon.icns",
      "iconSize": 80,
      "background": "assets/dmg-background.png",
      "window": {
        "width": 540,
        "height": 380
      },
      "contents": [
        { "x": 410, "y": 170, "type": "link", "path": "/Applications" },
        { "x": 130, "y": 170, "type": "file" }
      ]
    }
  }
}

5. Häufig verwendete Codevorlagen

Fenstererstellung

// main.js
const { app, BrowserWindow } = require('electron');
const path = require('path');

function createWindow() {
  const win = new BrowserWindow({
    width: 1200,
    height: 800,
    minWidth: 800,
    minHeight: 600,
    center: true,
    title: 'Meine App',
    icon: path.join(__dirname, 'assets', 'icon.png'),
    show: false,
    frame: true,
    resizable: true,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false,
      webSecurity: true
    }
  });

  // Fenster erst anzeigen, wenn Inhalt geladen ist
  win.once('ready-to-show', () => {
    win.show();
  });

  // Entwicklerwerkzeuge im Entwicklungsmodus öffnen
  if (process.env.NODE_ENV === 'development') {
    win.webContents.openDevTools();
  }

  // Seite laden
  if (process.env.WEBPACK_DEV_SERVER_URL) {
    win.loadURL(process.env.WEBPACK_DEV_SERVER_URL);
  } else {
    win.loadFile('index.html');
  }
}

app.whenReady().then(() => {
  createWindow();

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow();
    }
  });
});

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

IPC-Kommunikation (Preload-Brücke)

// preload.js
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
  // Zweiweg-Kommunikation
  getData: (params) => ipcRenderer.invoke('get-data', params),
  saveData: (data) => ipcRenderer.invoke('save-data', data),

  // Einweg-Kommunikation
  sendMessage: (message) => ipcRenderer.send('message', message),

  // Nachrichten empfangen
  onNotification: (callback) => {
    ipcRenderer.on('notification', (event, data) => callback(data));
  },

  // Fenstersteuerung
  minimizeWindow: () => ipcRenderer.send('window-minimize'),
  maximizeWindow: () => ipcRenderer.send('window-maximize'),
  closeWindow: () => ipcRenderer.send('window-close')
});

Lokaler Speicher (electron-store)

// main.js
const Store = require('electron-store').default;

const store = new Store();

// IPC-Handler für Datenspeicherung
const { ipcMain } = require('electron');

ipcMain.handle('get-setting', (event, key) => {
  return store.get(key);
});

ipcMain.handle('set-setting', (event, key, value) => {
  store.set(key, value);
  return { success: true };
});

ipcMain.handle('get-all-settings', () => {
  return store.store;
});

ipcMain.handle('clear-settings', () => {
  store.clear();
  return { success: true };
});

Fehlerbehandlung (global)

// main.js
const { app, dialog } = require('electron');

// Unhandled Promise Rejections abfangen
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', reason);
});

// Uncaught Exceptions abfangen
process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);

  dialog.showErrorBox(
    'Kritischer Fehler',
    `Die Anwendung wird beendet.\n\nFehler: ${error.message}`
  );

  app.quit();
});

// Renderer-Prozess-Absturz überwachen
app.on('render-process-gone', (event, webContents, details) => {
  console.error('Renderer-Prozess abgestürzt:', details.reason);

  const win = BrowserWindow.fromWebContents(webContents);
  if (win) {
    dialog.showMessageBox(win, {
      type: 'error',
      title: 'Fehler',
      message: 'Der Renderer-Prozess ist abgestürzt.',
      detail: `Grund: ${details.reason}`,
      buttons: ['OK', 'Neu starten']
    }).then(({ response }) => {
      if (response === 1) {
        app.relaunch();
        app.quit();
      }
    });
  }
});

6. Häufige Anfängerfehler-Vergleichstabelle

Fehlerdiagnose-Tabelle

Symptom	Ursache	Lösung	Priorität
module not found: electron	Electron nicht installiert	npm install electron --save-dev	🔴 Hoch
main.js not found	Falscher Pfad in package.json	main-Feld prüfen	🔴 Hoch
ipcRenderer is not defined	contextIsolation: true aktiviert	Preload-Skript verwenden	🔴 Hoch
Nachricht kommt nicht an	Falscher Kanalname	Kanalnamen exakt gleich schreiben	🟡 Mittel
Notification is not a constructor	Notification im Renderer verwendet	Über IPC aufrufen	🟡 Mittel
CORS-Fehler	API-Request im Renderer	Über Hauptprozess senden	🟡 Mittel
App startet nach Paketierung nicht	Falsche Pfade	app.isPackaged prüfen	🟠 Niedrig
APP-Absturz	uncaughtException	try-catch hinzufügen	🔴 Hoch
Speicherleck	IPC-Listener mehrfach registriert	removeListener() verwenden	🟡 Mittel

Fehlerbehebungs-Checkliste

☑ Node.js und npm korrekt installiert?
☑ Electron installiert (`npm list electron`)?
☑ `main`-Feld in `package.json` korrekt?
☑ Pfade in `main.js` korrekt?
☑ `contextIsolation: true` aktiviert?
☑ Preload-Skript konfiguriert?
☑ IPC-Kanalnamen exakt gleich?
☑ `invoke/handle` (nicht `send/on`) verwendet?
☑ Renderer-Prozess: Kein direkter Node.js-Zugriff?
☑ Hauptprozess: Keine DOM-Operationen?
☑ Fehlerbehandlung implementiert?
☑ Paketierung: `dependencies` (nicht `devDependencies`)?
☑ Pfade nach Paketierung mit `app.isPackaged` geprüft?

7. Häufig verwendete Drittanbieter-Plugins

Nach Kategorien sortiert

Datenspeicherung

Plugin	Zweck	Installation	Empfehlungsgrad
electron-store	Einfache persistene Datenspeicherung	npm install electron-store	⭐⭐⭐⭐⭐ (Sehr empfohlen)
lowdb	Leichtgewichtige lokale JSON-Datenbank	npm install lowdb	⭐⭐⭐⭐
nedb	Eingebettete NoSQL-Datenbank	npm install nedb	⭐⭐⭐

Logging

Plugin	Zweck	Installation	Empfehlungsgrad
electron-log	Professionelles Logging für Electron	npm install electron-log	⭐⭐⭐⭐⭐ (Sehr empfohlen)
winston	Vielseitiges Logging-Framework	npm install winston	⭐⭐⭐⭐

Aktualisierung

Plugin	Zweck	Installation	Empfehlungsgrad
electron-updater	Automatische Aktualisierung	npm install electron-updater	⭐⭐⭐⭐ (Für Produktion)

Sicherheit

Plugin	Zweck	Installation	Empfehlungsgrad
electron-devtools-installer	DevTools-Erweiterungen installieren	npm install electron-devtools-installer	⭐⭐⭐ (Für Entwicklung)

UI-Frameworks

Framework	Zweck	Webseite	Empfehlungsgrad
photon	Electron-UI-Kit im macOS-Stil	https://photonkit.com/	⭐⭐⭐ (Für einfache Apps)
buefy	Vue-UI-Komponenten für Electron	https://buefy.org/	⭐⭐⭐⭐ (Für Vue-Projekte)

Plugin-Auswahlentscheidungshilfe

Brauchen Sie...                          → Verwenden Sie...
─────────────────────────────────────────────────────────────────
Einfache Datenspeicherung?              → electron-store
Datenbankähnliche Struktur?             → lowdb oder nedb
Professionelles Logging?                  → electron-log
Automatische Aktualisierung?            → electron-updater
DevTools-Erweiterungen?                → electron-devtools-installer
Schönes UI im macOS-Stil?             → photon
Vue-UI-Komponenten?                   → buefy

Zusammenfassung

Dieser Anhang bietet eine schnelle Referenz für:

• Kernmodule-Kurzreferenz (nach Häufigkeit sortiert)
• Haupt- vs. Renderer-Prozess-Unterschiede (Vergleichstabelle)
• IPC-Kommunikationsmethoden (senden, überwachen, antworten)
• Paketierungskonfigurationsvorlagen (Multi-Plattform, kopieren und verwenden)
• Häufig verwendete Codevorlagen (Fenstererstellung, IPC, Speicherung)
• Häufige Anfängerfehler-Vergleichstabelle (schnelle Fehlersuche)
• Häufig verwendete Drittanbieter-Plugins (nach Szenario sortiert)

Bewahren Sie dieses Dokument als Schnellnachschlagewerk auf!