@madrimov/electron-window-state

Save and restore Electron window position, size, and state across sessions. Supports multiple windows and multi-monitor setups.

Features

• Saves & restores window position, size, maximized and fullscreen state
• Multi-monitor safe — falls back to defaults if saved position is off-screen
• Multiple windows — use a unique key per window
• Debounced saving — no performance hit on resize/move events
• Zero runtime dependencies
• Works with Electron 28+

Installation

npm install @madrimov/electron-window-state

Quick Start

import { app, BrowserWindow } from 'electron';
import { createWindowState } from '@madrimov/electron-window-state';

app.whenReady(() => {
  const state = createWindowState({
    key: 'main',
    defaultWidth: 1200,
    defaultHeight: 800,
  });

  const win = new BrowserWindow({
    x: state.x,
    y: state.y,
    width: state.width,
    height: state.height,
    // restore maximized state after creation:
  });

  // Attach tracking — saves automatically on move, resize, close
  state.manage(win);

  // Restore maximized / fullscreen state
  if (state.isMaximized) win.maximize();
  if (state.isFullScreen) win.setFullScreen(true);
});

Multiple Windows

Use a unique key for each window:

const mainState = createWindowState({ key: 'main', defaultWidth: 1200, defaultHeight: 800 });
const settingsState = createWindowState({ key: 'settings', defaultWidth: 600, defaultHeight: 400 });

Each window saves its state to a separate file:

• userData/window-state-main.json
• userData/window-state-settings.json

API

createWindowState(options?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | key | string | 'main' | Unique identifier for this window | | defaultWidth | number | 800 | Width when no saved state exists | | defaultHeight | number | 600 | Height when no saved state exists | | cwd | string | app.getPath('userData') | Directory for the JSON file |

State Properties

| Property | Type | Description | |----------|------|-------------| | x | number | Window x position | | y | number | Window y position | | width | number | Window width | | height | number | Window height | | isMaximized | boolean | Was window maximized when last closed? | | isFullScreen | boolean | Was window in fullscreen when last closed? |

State Methods

| Method | Description | |--------|-------------| | manage(win) | Attach tracking to a BrowserWindow | | save() | Manually save current state | | reset() | Reset to defaults and delete saved file |

Multi-Monitor Safety

If the saved window position falls outside all current displays (e.g. after disconnecting a monitor), the state automatically resets to defaults so the window always appears visible.

Requirements

• Node.js >= 18.0.0
• Electron >= 28.0.0

License

MIT