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

> Discover how Lepton persists window size, position, and state across restarts using electron-window-state. Ensure a seamless user experience with automatic state restoration.

- Repository: [CosmoX/Lepton](https://github.com/hackjutsu/lepton)
- Tags: internals
- Published: 2026-02-23

---

**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](https://github.com/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`](https://github.com/hackjutsu/Lepton/blob/main/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`](https://github.com/hackjutsu/Lepton/blob/main/main.js), Lepton requires the helper module:

```javascript
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:

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

```

This call attempts to load existing state from [`window-state.json`](https://github.com/hackjutsu/Lepton/blob/main/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:

```javascript
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:

```javascript
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`](https://github.com/hackjutsu/Lepton/blob/main/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`](https://github.com/hackjutsu/Lepton/blob/main/main.js):

```javascript
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`](https://github.com/hackjutsu/Lepton/blob/main/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`](https://github.com/hackjutsu/Lepton/blob/main/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`](https://github.com/hackjutsu/Lepton/blob/main/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`](https://github.com/hackjutsu/Lepton/blob/main/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`](https://github.com/hackjutsu/Lepton/blob/main/window-state.json) accordingly, ensuring the window returns to the exact same view mode on the next launch.