How Lepton Persists Window Size, Position, and State Across Application Restarts

Lepton uses the electron-window-state npm package in its main process to automatically save and restore window dimensions, screen coordinates, and maximized or full-screen states between sessions.

The open-source Gist client hackjutsu/Lepton implements seamless window state persistence to ensure users return to the exact same workspace layout every time they launch the application. By leveraging a specialized Electron helper module, Lepton eliminates the need for manual state management while providing reliable fallback defaults.

Understanding Window State Persistence in Electron

Desktop applications built with Electron face a common challenge: remembering where the user positioned the window and how large they sized it before closing the app. Without explicit persistence logic, every restart resets the window to hardcoded defaults, creating a frustrating user experience.

Lepton solves this by integrating electron-window-state, a lightweight utility that handles the complex lifecycle of reading, caching, and writing window metadata to disk.

How Lepton Implements Window State Persistence

The persistence logic resides entirely within main.js, Lepton's main process entry point. The implementation follows a four-step pattern: import the module, initialize state with defaults, apply geometry to the window constructor, and enable automatic management.

Importing the electron-window-state Module

At the top of main.js, Lepton requires the helper module:

const windowStateKeeper = require('electron-window-state')

This import exposes a factory function that manages the entire persistence workflow, including file I/O operations within Electron's user data directory.

Initializing State with Default Dimensions

When preparing to create the main window, Lepton invokes windowStateKeeper with fallback dimensions to ensure first-time users see a reasonably sized window:

let mainWindowState = windowStateKeeper({
  defaultWidth: 1100,
  defaultHeight: 800
})

This call attempts to load existing state from window-state.json in the user data path. If the file doesn't exist—such as during initial launch—the returned object contains the specified default values instead.

Applying Saved Geometry to BrowserWindow

Lepton passes the state object's properties directly into the BrowserWindow constructor to position the window exactly where it was last seen:

mainWindow = new BrowserWindow({
  width: mainWindowState.width,
  height: mainWindowState.height,
  x: mainWindowState.x,
  y: mainWindowState.y,
  // …other options…
})

This ensures the window restores to its previous screen coordinates and dimensions immediately upon creation, before the user sees any visual reset or repositioning.

Enabling Automatic State Management

After creating the window, Lepton delegates all future state tracking to the helper module:

mainWindowState.manage(mainWindow)

This single line attaches event listeners for resize, move, close, and state changes like maximization or full-screen toggles. The helper automatically writes updates to window-state.json in the background, ensuring persistence occurs without blocking the main process or requiring manual file handling.

Complete Implementation Example

The following condensed example demonstrates the complete pattern used in Lepton's main.js:

const { app, BrowserWindow } = require('electron')
const windowStateKeeper = require('electron-window-state')

function createMainWindow () {
  // Load previous state or use defaults
  const winState = windowStateKeeper({
    defaultWidth: 1100,
    defaultHeight: 800
  })

  // Create window with saved geometry
  const win = new BrowserWindow({
    x: winState.x,
    y: winState.y,
    width: winState.width,
    height: winState.height,
    webPreferences: {
      nodeIntegration: true
    }
  })

  // Enable automatic persistence
  winState.manage(win)
  
  win.loadURL(`file://${__dirname}/index.html`)
}

app.whenReady().then(createMainWindow)

Where Lepton Stores Window State Data

The electron-window-state module persists data to a JSON file named window-state.json located in Electron's userData directory. On most systems, this resolves to:

• Windows: %APPDATA%/Lepton/window-state.json
• macOS: ~/Library/Application Support/Lepton/window-state.json
• Linux: ~/.config/Lepton/window-state.json

This file contains the last known width, height, x, y coordinates, plus boolean flags for isMaximized and isFullScreen. The module handles all read and write operations atomically to prevent corruption during unexpected shutdowns.

Summary

• Lepton relies on the electron-window-state npm package to handle window persistence without custom file I/O code.
• The implementation in main.js follows a four-step pattern: import the module, initialize with default dimensions (1100×800), apply saved geometry to BrowserWindow, and call manage() to enable automatic updates.
• Window metadata writes to window-state.json in the user data directory whenever the window moves, resizes, or changes state, ensuring seamless restoration across application restarts.

Frequently Asked Questions

What package does Lepton use to persist window state?

Lepton uses electron-window-state, a specialized Electron helper module that abstracts the complexity of reading and writing window geometry to disk. This package handles all file operations, event listening, and fallback logic automatically.

Where does Lepton store the window state file?

The state persists to a file named window-state.json inside Electron's userData directory. The exact path varies by operating system—typically within %APPDATA%/Lepton on Windows, ~/Library/Application Support/Lepton on macOS, or ~/.config/Lepton on Linux.

What are the default window dimensions in Lepton?

If no previous state exists—such as during the first launch—Lepton initializes the window with a default width of 1100 pixels and height of 800 pixels. These values pass to windowStateKeeper() as fallback parameters before creating the BrowserWindow instance.

Does Lepton persist maximized and full-screen states?

Yes. The electron-window-state module automatically tracks and restores maximized and full-screen states alongside window dimensions and position. When users toggle these states, the helper updates window-state.json accordingly, ensuring the window returns to the exact same view mode on the next launch.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}