Claude Skill

desktop-multiwindow-electron

Multi-window management, WebContentsView, BaseWindow, window lifecycle, inter-window communication, state persistence

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_desktop-multiwindow-electron_skills_desktop-multiwindow-electron-707467a.zip · 15 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/desktop-multiwindow-electron/skills/desktop-multiwindow-electron
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Electron Multi-Window Patterns

Quick Guide: Use BrowserWindow for single-view windows. Use BaseWindow + WebContentsView for multi-view layouts (tabs, split panes, panels). BrowserView is deprecated since Electron 30 -- migrate to WebContentsView. Track windows with a Map<string, BrowserWindow> registry. Communicate between windows via the main process or MessagePort for direct renderer-to-renderer channels. Persist window bounds manually or use the upcoming windowStatePersistence API. Always close webContents explicitly when using BaseWindow -- unlike BrowserWindow, it does not auto-cleanup.


<critical_requirements>

CRITICAL: Before Using This Skill

(You MUST close webContents explicitly when destroying a BaseWindow -- it does not auto-cleanup like BrowserWindow, causing memory leaks)

(You MUST use WebContentsView instead of BrowserView -- BrowserView is deprecated since Electron 30)

(You MUST route all inter-window communication through the main process or MessagePort -- never access another window's renderer directly)

(You MUST validate that saved window bounds are on a visible display before restoring -- monitors may disconnect between sessions)

</critical_requirements>


Auto-detection: multi-window, BaseWindow, WebContentsView, BrowserView migration, contentView, addChildView, removeChildView, parent window, child window, modal window, window registry, MessagePort, MessageChannelMain, window state persistence, screen API, workArea, getAllDisplays, split view, tabs, panels, window lifecycle, ready-to-show, window-all-closed

When to use:

  • Creating multi-view layouts (tabs, split panes, embedded panels) with BaseWindow + WebContentsView
  • Managing multiple BrowserWindow instances with a window registry
  • Migrating from deprecated BrowserView to WebContentsView
  • Setting up parent/child or modal windows
  • Communicating between windows (via main process relay or MessagePort)
  • Persisting and restoring window position, size, and display state
  • Placing windows on specific monitors using the screen API

When NOT to use:

  • Single-window apps with one view (BrowserWindow is sufficient on its own)
  • Choosing a UI framework for the renderer
  • IPC patterns between main and a single renderer (basic IPC is outside multi-window scope)
  • Styling or layout within a single renderer

Key patterns covered:

  • BaseWindow + WebContentsView for multi-view layouts
  • BrowserView to WebContentsView migration
  • Window lifecycle events (ready-to-show, close, closed)
  • Parent/child and modal windows
  • Window registry with Map-based tracking
  • Inter-window communication via main process and MessagePort
  • Window state persistence (bounds, maximized, fullscreen)
  • Multi-monitor placement with screen API



<decision_framework>

Decision Framework

Window Type Selection

How many web views does this window need?
+-- One full-size view?
|   +-- BrowserWindow (simpler, automatic lifecycle)
+-- Multiple views (tabs, split pane, sidebar + content)?
|   +-- BaseWindow + WebContentsView
+-- Frameless window with custom layout?
    +-- One view? -> BrowserWindow with frame: false
    +-- Multiple views? -> BaseWindow with frame: false

Inter-Window Communication

How should windows communicate?
+-- Simple, infrequent messages?
|   +-- Main process relay (ipcMain/webContents.send)
+-- High-frequency or streaming data?
|   +-- MessagePort (direct renderer-to-renderer after setup)
+-- Shared state across windows?
    +-- Main process as single source of truth, push updates via IPC

Window Relationship

What is the relationship between windows?
+-- Independent (editor, browser tabs)?
|   +-- Separate BrowserWindow instances, window registry
+-- Always above parent (inspector, palette)?
|   +-- Child window: { parent: parentWin }
+-- Blocks parent (save dialog, settings confirmation)?
    +-- Modal window: { parent: parentWin, modal: true }

</decision_framework>


Detailed resources:


<red_flags>

RED FLAGS

Critical Issues:

  • Not closing webContents when destroying a BaseWindow -- causes memory leaks (BrowserWindow auto-cleans, BaseWindow does not)
  • Using deprecated BrowserView instead of WebContentsView -- deprecated since Electron 30
  • Direct renderer-to-renderer communication bypassing the main process -- violates process isolation
  • Restoring window bounds without checking if the target display still exists -- window appears off-screen

Architecture Issues:

  • Using BaseWindow for single-view windows -- unnecessary complexity, use BrowserWindow
  • Using BrowserView.setAutoResize() patterns with WebContentsView -- no equivalent exists, use manual resize listeners
  • Storing BrowserWindow objects as Map values without cleaning up on closed -- stale references
  • Creating child windows from the renderer process -- always create from main

Common Mistakes:

  • Expecting ready-to-show on BaseWindow -- it fires on BrowserWindow only; for BaseWindow, listen on view.webContents
  • Forgetting that WebContentsView defaults to white background (BrowserView defaulted to transparent) -- set "#00000000" explicitly
  • Using ipcRenderer.send() to transfer MessagePort -- only postMessage() can transfer ports
  • Placing windows using display.bounds instead of display.workArea -- window ends up behind taskbar/dock
  • Not handling display-removed event -- window references a disconnected monitor

Gotchas & Edge Cases:

  • Re-adding a child view with addChildView() moves it to the top of the z-order -- this is intentional, not a bug
  • setBounds() coordinates are relative to the parent view, not the screen
  • On macOS, modal windows display as sheets attached to the parent window
  • win.getBounds() returns the outer frame bounds on some platforms -- content area may differ
  • Each WebContentsView runs its own renderer process -- resource usage scales linearly with view count
  • MessagePortMain requires calling .start() before messages are delivered -- they queue until then

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(You MUST close webContents explicitly when destroying a BaseWindow -- it does not auto-cleanup like BrowserWindow, causing memory leaks)

(You MUST use WebContentsView instead of BrowserView -- BrowserView is deprecated since Electron 30)

(You MUST route all inter-window communication through the main process or MessagePort -- never access another window's renderer directly)

(You MUST validate that saved window bounds are on a visible display before restoring -- monitors may disconnect between sessions)

Failure to follow these rules will cause memory leaks, deprecated API warnings, broken inter-process communication, or off-screen windows.

</critical_reminders>

Files (skills)
  • examples
    • core.md 16.1 KB
      Loading…
    • inter-window-communication.md 7.7 KB
      Loading…
  • reference.md 7 KB
    Loading…
  • SKILL.md 15.8 KB
    ---
    name: desktop-multiwindow-electron
    description: Multi-window management, WebContentsView, BaseWindow, window lifecycle, inter-window communication, state persistence
    ---
    
    # Electron Multi-Window Patterns
    
    > **Quick Guide:** Use `BrowserWindow` for single-view windows. Use `BaseWindow` + `WebContentsView` for multi-view layouts (tabs, split panes, panels). `BrowserView` is deprecated since Electron 30 -- migrate to `WebContentsView`. Track windows with a `Map<string, BrowserWindow>` registry. Communicate between windows via the main process or `MessagePort` for direct renderer-to-renderer channels. Persist window bounds manually or use the upcoming `windowStatePersistence` API. Always close `webContents` explicitly when using `BaseWindow` -- unlike `BrowserWindow`, it does not auto-cleanup.
    
    ---
    
    <critical_requirements>
    
    ## CRITICAL: Before Using This Skill
    
    **(You MUST close `webContents` explicitly when destroying a `BaseWindow` -- it does not auto-cleanup like `BrowserWindow`, causing memory leaks)**
    
    **(You MUST use `WebContentsView` instead of `BrowserView` -- `BrowserView` is deprecated since Electron 30)**
    
    **(You MUST route all inter-window communication through the main process or `MessagePort` -- never access another window's renderer directly)**
    
    **(You MUST validate that saved window bounds are on a visible display before restoring -- monitors may disconnect between sessions)**
    
    </critical_requirements>
    
    ---
    
    **Auto-detection:** multi-window, BaseWindow, WebContentsView, BrowserView migration, contentView, addChildView, removeChildView, parent window, child window, modal window, window registry, MessagePort, MessageChannelMain, window state persistence, screen API, workArea, getAllDisplays, split view, tabs, panels, window lifecycle, ready-to-show, window-all-closed
    
    **When to use:**
    
    - Creating multi-view layouts (tabs, split panes, embedded panels) with BaseWindow + WebContentsView
    - Managing multiple BrowserWindow instances with a window registry
    - Migrating from deprecated BrowserView to WebContentsView
    - Setting up parent/child or modal windows
    - Communicating between windows (via main process relay or MessagePort)
    - Persisting and restoring window position, size, and display state
    - Placing windows on specific monitors using the screen API
    
    **When NOT to use:**
    
    - Single-window apps with one view (`BrowserWindow` is sufficient on its own)
    - Choosing a UI framework for the renderer
    - IPC patterns between main and a single renderer (basic IPC is outside multi-window scope)
    - Styling or layout within a single renderer
    
    **Key patterns covered:**
    
    - BaseWindow + WebContentsView for multi-view layouts
    - BrowserView to WebContentsView migration
    - Window lifecycle events (ready-to-show, close, closed)
    - Parent/child and modal windows
    - Window registry with Map-based tracking
    - Inter-window communication via main process and MessagePort
    - Window state persistence (bounds, maximized, fullscreen)
    - Multi-monitor placement with screen API
    
    ---
    
    <philosophy>
    
    ## Philosophy
    
    Electron's window model has two tiers. **BrowserWindow** is the simple path: one window, one web view, automatic lifecycle management. **BaseWindow + WebContentsView** is the flexible path: one window shell containing multiple independently managed web views, each with its own renderer process and preload script.
    
    The key architectural decision: **use BrowserWindow for single-view windows, BaseWindow for multi-view layouts.** BaseWindow trades convenience for control -- you manage view lifecycle, bounds, and cleanup explicitly.
    
    **When to use BaseWindow + WebContentsView:**
    
    - Tab bars, split editors, preview panels, embedded browser views
    - Any layout where multiple independent web pages share one OS window
    - Applications migrating from deprecated BrowserView
    
    **When NOT to use BaseWindow:**
    
    - Single-view windows (BrowserWindow is simpler and handles cleanup automatically)
    - Windows that only need a toolbar or status bar (a single BrowserWindow with HTML layout is sufficient)
    
    </philosophy>
    
    ---
    
    <patterns>
    
    ## Core Patterns
    
    ### Pattern 1: BaseWindow with WebContentsView
    
    BaseWindow is the window shell; WebContentsView instances are the content. Each view has its own renderer process and preload script.
    
    ```javascript
    const { BaseWindow, WebContentsView } = require("electron");
    
    const win = new BaseWindow({ width: 1200, height: 800 });
    
    const sidebar = new WebContentsView({
      webPreferences: { preload: path.join(__dirname, "preload.js") },
    });
    const main = new WebContentsView({
      webPreferences: { preload: path.join(__dirname, "preload.js") },
    });
    
    win.contentView.addChildView(sidebar);
    win.contentView.addChildView(main);
    
    const SIDEBAR_WIDTH = 250;
    sidebar.setBounds({ x: 0, y: 0, width: SIDEBAR_WIDTH, height: 800 });
    main.setBounds({ x: SIDEBAR_WIDTH, y: 0, width: 950, height: 800 });
    
    sidebar.webContents.loadFile("sidebar.html");
    main.webContents.loadFile("main.html");
    ```
    
    **Key point:** Each WebContentsView needs its own `webPreferences` and preload script. BaseWindow has no `webContents` of its own. See [examples/core.md](examples/core.md) for complete split-view and tab examples with resize handling.
    
    ---
    
    ### Pattern 2: BrowserView to WebContentsView Migration
    
    BrowserView is deprecated since Electron 30. Migration is straightforward -- constructors have the same shape.
    
    | Deprecated (BrowserView)                 | Replacement (WebContentsView)                             |
    | ---------------------------------------- | --------------------------------------------------------- |
    | `new BrowserView(opts)`                  | `new WebContentsView(opts)`                               |
    | `win.addBrowserView(view)`               | `win.contentView.addChildView(view)`                      |
    | `win.removeBrowserView(view)`            | `win.contentView.removeChildView(view)`                   |
    | `win.getBrowserViews()`                  | `win.contentView.children`                                |
    | `win.setTopBrowserView(view)`            | `win.contentView.addChildView(view)` (re-adding reorders) |
    | `view.setAutoResize({ vertical: true })` | Manual resize via `win.on("resize", ...)` + `setBounds()` |
    
    **Gotcha:** WebContentsView defaults to a white background; BrowserView defaulted to transparent. Set `view.setBackgroundColor("#00000000")` for transparency.
    
    See [examples/core.md](examples/core.md) for the complete migration pattern with auto-resize replacement.
    
    ---
    
    ### Pattern 3: Window Lifecycle Events
    
    Window events fire in a predictable order. Use `ready-to-show` to prevent visual flash, `close` to intercept (confirmations, state saving), `closed` for final cleanup.
    
    ```javascript
    const win = new BrowserWindow({ show: false });
    
    // Prevent white flash -- show only after first paint
    win.once("ready-to-show", () => {
      win.show();
    });
    
    // Intercept close for unsaved changes
    win.on("close", (event) => {
      if (hasUnsavedChanges()) {
        event.preventDefault();
        promptSaveDialog(win);
      }
    });
    
    // Final cleanup after window is gone
    win.on("closed", () => {
      windowRegistry.delete(win.id);
    });
    ```
    
    **Gotcha:** `ready-to-show` fires on `BrowserWindow` (which owns a `webContents`) but NOT on `BaseWindow` (which has no `webContents`). For BaseWindow, listen on the individual WebContentsView's `webContents` instead: `view.webContents.once("ready-to-show", ...)`.
    
    See [examples/core.md](examples/core.md) for the full lifecycle sequence and BaseWindow workaround.
    
    ---
    
    ### Pattern 4: Parent/Child and Modal Windows
    
    Child windows always appear above their parent. Modal windows additionally disable the parent until closed.
    
    ```javascript
    const parent = new BrowserWindow({ width: 800, height: 600 });
    
    // Child window: always on top of parent, non-blocking
    const child = new BrowserWindow({
      parent,
      width: 400,
      height: 300,
    });
    
    // Modal window: blocks parent interaction
    const modal = new BrowserWindow({
      parent,
      modal: true,
      show: false,
      width: 500,
      height: 400,
    });
    modal.once("ready-to-show", () => modal.show());
    ```
    
    **Platform behavior:** On macOS, modal child windows display as sheets attached to the parent. On Windows/Linux, they display as separate windows with the parent disabled.
    
    See [examples/core.md](examples/core.md) for confirmation dialogs and settings windows.
    
    ---
    
    ### Pattern 5: Window Registry
    
    Track all open windows with a Map for reliable lookup, messaging, and cleanup.
    
    ```javascript
    const windowRegistry = new Map();
    
    function createWindow(id, options) {
      const win = new BrowserWindow(options);
      windowRegistry.set(id, win);
    
      win.on("closed", () => {
        windowRegistry.delete(id);
      });
    
      return win;
    }
    
    // Find and focus a window by ID
    function focusWindow(id) {
      const win = windowRegistry.get(id);
      if (!win) return;
      if (win.isMinimized()) win.restore();
      win.focus();
    }
    ```
    
    **Key point:** Use string IDs (not window objects) as keys. Clean up on `closed` event. The registry enables "show existing or create new" patterns for settings, about, and preferences windows.
    
    See [examples/core.md](examples/core.md) for the full singleton window pattern.
    
    ---
    
    ### Pattern 6: Inter-Window Communication
    
    Two patterns: **main process relay** for simple messages, **MessagePort** for direct high-frequency renderer-to-renderer channels.
    
    ```javascript
    // Pattern A: Main process relay
    ipcMain.on("message-to-window", (_event, targetId, channel, data) => {
      const target = windowRegistry.get(targetId);
      if (target) target.webContents.send(channel, data);
    });
    
    // Pattern B: MessagePort -- direct renderer-to-renderer
    const { MessageChannelMain } = require("electron");
    const { port1, port2 } = new MessageChannelMain();
    
    window1.webContents.postMessage("port", null, [port1]);
    window2.webContents.postMessage("port", null, [port2]);
    ```
    
    **Key point:** Main process relay is simpler but adds latency. MessagePort creates a direct channel after initial setup. Use `postMessage` (not `send`) to transfer ports.
    
    See [examples/inter-window-communication.md](examples/inter-window-communication.md) for complete examples of both patterns.
    
    ---
    
    ### Pattern 7: Window State Persistence
    
    Save and restore window bounds, maximized state, and display information across sessions.
    
    ```javascript
    function saveWindowState(win, stateFile) {
      const bounds = win.getBounds();
      const state = {
        bounds,
        isMaximized: win.isMaximized(),
        isFullScreen: win.isFullScreen(),
        displayId: screen.getDisplayMatching(bounds).id,
      };
      fs.writeFileSync(stateFile, JSON.stringify(state));
    }
    ```
    
    **Key point:** Always validate restored bounds against current displays -- a monitor may have been disconnected. Fall back to the primary display's work area if the saved display is unavailable.
    
    See [examples/core.md](examples/core.md) for the complete save/restore cycle with multi-monitor validation.
    
    ---
    
    ### Pattern 8: Multi-Monitor Placement
    
    Use the `screen` API to enumerate displays, find work areas, and place windows on specific monitors.
    
    ```javascript
    const { screen } = require("electron");
    
    const displays = screen.getAllDisplays();
    const externalDisplay = displays.find(
      (d) => d.bounds.x !== 0 || d.bounds.y !== 0,
    );
    
    if (externalDisplay) {
      const win = new BrowserWindow({
        x: externalDisplay.bounds.x,
        y: externalDisplay.bounds.y,
        width: 800,
        height: 600,
      });
    }
    ```
    
    **Key point:** Use `workArea` (not `bounds`) to avoid placing windows behind taskbars/docks. Listen for `display-added`, `display-removed`, and `display-metrics-changed` events to react to monitor changes at runtime.
    
    See [examples/core.md](examples/core.md) for display enumeration and safe placement.
    
    </patterns>
    
    ---
    
    <decision_framework>
    
    ## Decision Framework
    
    ### Window Type Selection
    
    ```
    How many web views does this window need?
    +-- One full-size view?
    |   +-- BrowserWindow (simpler, automatic lifecycle)
    +-- Multiple views (tabs, split pane, sidebar + content)?
    |   +-- BaseWindow + WebContentsView
    +-- Frameless window with custom layout?
        +-- One view? -> BrowserWindow with frame: false
        +-- Multiple views? -> BaseWindow with frame: false
    ```
    
    ### Inter-Window Communication
    
    ```
    How should windows communicate?
    +-- Simple, infrequent messages?
    |   +-- Main process relay (ipcMain/webContents.send)
    +-- High-frequency or streaming data?
    |   +-- MessagePort (direct renderer-to-renderer after setup)
    +-- Shared state across windows?
        +-- Main process as single source of truth, push updates via IPC
    ```
    
    ### Window Relationship
    
    ```
    What is the relationship between windows?
    +-- Independent (editor, browser tabs)?
    |   +-- Separate BrowserWindow instances, window registry
    +-- Always above parent (inspector, palette)?
    |   +-- Child window: { parent: parentWin }
    +-- Blocks parent (save dialog, settings confirmation)?
        +-- Modal window: { parent: parentWin, modal: true }
    ```
    
    </decision_framework>
    
    ---
    
    **Detailed resources:**
    
    - [examples/core.md](examples/core.md) - BaseWindow + WebContentsView, lifecycle, registry, state persistence, multi-monitor
    - [examples/inter-window-communication.md](examples/inter-window-communication.md) - Main process relay, MessagePort, typed channels
    - [reference.md](reference.md) - API quick-reference tables, migration checklist, event order
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    **Critical Issues:**
    
    - Not closing `webContents` when destroying a `BaseWindow` -- causes memory leaks (BrowserWindow auto-cleans, BaseWindow does not)
    - Using deprecated `BrowserView` instead of `WebContentsView` -- deprecated since Electron 30
    - Direct renderer-to-renderer communication bypassing the main process -- violates process isolation
    - Restoring window bounds without checking if the target display still exists -- window appears off-screen
    
    **Architecture Issues:**
    
    - Using `BaseWindow` for single-view windows -- unnecessary complexity, use `BrowserWindow`
    - Using `BrowserView.setAutoResize()` patterns with `WebContentsView` -- no equivalent exists, use manual resize listeners
    - Storing `BrowserWindow` objects as Map values without cleaning up on `closed` -- stale references
    - Creating child windows from the renderer process -- always create from main
    
    **Common Mistakes:**
    
    - Expecting `ready-to-show` on `BaseWindow` -- it fires on `BrowserWindow` only; for `BaseWindow`, listen on `view.webContents`
    - Forgetting that `WebContentsView` defaults to white background (BrowserView defaulted to transparent) -- set `"#00000000"` explicitly
    - Using `ipcRenderer.send()` to transfer `MessagePort` -- only `postMessage()` can transfer ports
    - Placing windows using `display.bounds` instead of `display.workArea` -- window ends up behind taskbar/dock
    - Not handling `display-removed` event -- window references a disconnected monitor
    
    **Gotchas & Edge Cases:**
    
    - Re-adding a child view with `addChildView()` moves it to the top of the z-order -- this is intentional, not a bug
    - `setBounds()` coordinates are relative to the parent view, not the screen
    - On macOS, modal windows display as sheets attached to the parent window
    - `win.getBounds()` returns the outer frame bounds on some platforms -- content area may differ
    - Each `WebContentsView` runs its own renderer process -- resource usage scales linearly with view count
    - `MessagePortMain` requires calling `.start()` before messages are delivered -- they queue until then
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(You MUST close `webContents` explicitly when destroying a `BaseWindow` -- it does not auto-cleanup like `BrowserWindow`, causing memory leaks)**
    
    **(You MUST use `WebContentsView` instead of `BrowserView` -- `BrowserView` is deprecated since Electron 30)**
    
    **(You MUST route all inter-window communication through the main process or `MessagePort` -- never access another window's renderer directly)**
    
    **(You MUST validate that saved window bounds are on a visible display before restoring -- monitors may disconnect between sessions)**
    
    **Failure to follow these rules will cause memory leaks, deprecated API warnings, broken inter-process communication, or off-screen windows.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.