electron-store

Simple, encrypted JSON persistence for your Electron app — save user settings, window state, and cache across the main and renderer processes.

Library
npm
v12.0.0
5,030 stars
MIT License

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum. How we score it →
66 /100 Good
Development Activity 60
Maintenance 52
Community 52
Maturity 60
Momentum 40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation. How we score it →
58 /100 Fair
Architecture 75
Code Quality 82
Innovation 40
Learning Curve 35

electron-store solves a gap in Electron itself: the framework has no built-in way to persist user settings, window state, or cache between app launches. Built by Sindre Sorhus as a thin Electron-aware wrapper around his own conf package, it writes a single JSON file to the OS-conventional user data directory, handles the main/renderer process split transparently via IPC, and exposes a small get/set/has/delete API with dot-notation for nested keys.

Beyond plain key-value storage, it supports JSON Schema validation of stored data, versioned migrations that run automatically when the app’s version changes, optional AES encryption for obscuring (not securing) the file contents, and change-watching callbacks (onDidChange/onDidAnyChange) so multiple processes can react to updates. It’s explicitly scoped to small data — settings, preferences, cached values — not a database replacement for large datasets.

What You Get

  • A Store class (subclassing conf) that reads and writes a JSON config file in Electron’s standard userData directory automatically
  • Transparent main/renderer process support — call Store.initRenderer() once in the main process and use new Store() freely in either process
  • Dot-notation access to nested properties (store.get('foo.bar')) with an option to disable it and treat keys as literal strings
  • JSON Schema-based validation of stored values via ajv, with configurable defaults for missing keys
  • Versioned migration hooks that run automatically when projectVersion changes, plus a beforeEachMigration callback for logging
  • Optional at-rest obfuscation via encryptionKey and a choice of aes-256-cbc, aes-256-gcm (authenticated), or aes-256-ctr
  • Atomic writes, so a crash mid-save can’t corrupt the existing config file
  • Change observers (onDidChange, onDidAnyChange) and a watch option to react to edits made by other processes

Common Use Cases

  • Persisting user preferences (theme, language, feature toggles) between launches of a desktop app
  • Remembering window size, position, and last-open-tab state so the app resumes where the user left it
  • Caching small amounts of API response data or computed values locally to avoid refetching on every launch
  • Storing per-install app state (onboarding completed, last-seen version) to drive one-time UI flows
  • Sharing a config store safely between an Electron app’s main and renderer processes without hand-rolled IPC

Under The Hood

Architecture

The entire package is a single ~80-line index.js file exporting one class, ElectronStore, that extends conf’s Conf class rather than reimplementing file persistence. On construction it branches on process.type: in the renderer process it calls electron.ipcRenderer.sendSync('electron-store-get-data') to synchronously fetch the default cwd and appVersion from the main process (set up once via an ipcMain.on handler in initDataListener), while in the main process it reads app.getPath('userData') and app.getVersion() directly. It then remaps its own name/cwd options onto conf’s configName/cwd before calling super(options), meaning nearly all actual storage, validation, migration, and encryption logic lives in the upstream conf package — this module’s real contribution is the Electron-specific main/renderer bridging and an openInEditor() convenience method that shells out via Electron’s shell.openPath.

Tech Stack

Published as native ESM only ("type": "module", no CommonJS export), requiring Node.js 20+ and Electron 30+. Its only runtime dependencies are conf (^15) for the actual persistence engine and type-fest (^5) for TypeScript utility types used in index.d.ts. There is no build step — the package ships the same ESM source it’s authored in, with hand-written .d.ts type definitions rather than a generated output.

Code Quality

Tests use ava together with execa to spawn a real electron binary against small fixture scripts (fixture.js, fixture-cwd.js) and assert on the JSON files those fixtures actually write to disk — an integration-style test against real Electron rather than mocks. Type correctness is checked separately with tsd against index.test-d.ts, and xo (ESLint preset) lints the source; all three (xo && ava && tsd) run as the test script and in GitHub Actions CI on macOS. Error handling is minimal but intentional: missing renderer initialization and failed openInEditor calls throw explicit Errors rather than failing silently.

What Makes It Unique

The package doesn’t reinvent config persistence — it defers essentially all of that to the well-established conf library — and instead solves the one problem specific to Electron: safely constructing and sharing a config store across the main and renderer processes without every consumer having to hand-roll IPC calls or worry about which process owns the file path. That narrow, single-purpose scope is itself the design choice, and its close family of sibling electron-* utility packages from the same author reinforces that this is meant to be one composable piece rather than a general-purpose framework.

Used by 14 apps in this directory

TypeScript
99%
AGPL 3.0

Cherry Studio

AI Assistants

53,308

All-in-one AI desktop client with 300+ assistants and multi-model support

View details
89
Repo Health
84
Technical
70
Dependency
Built with
TypeScript 99%
Updated 1 weeks ago
JavaScript
98%
Apache 2.0

drawio-desktop

Design Tools · Productivity

63,856

The offline-first diagram editor that puts security above all else — no account, no data leaving your machine, no compromises.

View details
88
Repo Health
63
Technical
70
Dependency
Built with
JavaScript 98%
Updated 1 weeks ago
TypeScript
94%
AGPL 3.0

Element Web

Collaboration · Team Chat

13,641

A polished, self-hostable Matrix client for secure, decentralized messaging and collaboration that puts your organization in full control of its data.

View details
96
Repo Health
83
Technical
64
Dependency
Built with
TypeScript 94%
Updated 1 weeks ago
JavaScript
88%
GPL 3.0

Glass by Pickle

AI Assistants

7,604

A privacy-first desktop AI assistant that sees your screen, hears your meetings, and turns live context into structured summaries—without sending a single byte to the cloud.

View details
43
Repo Health
76
Technical
68
Dependency
Built with
JavaScript 88%
TypeScript 12%
Updated 1 years ago
Python
56%
AGPL 3.0

Glean

Bookmarks Archiving · Knowledge Management

874

Self-hosted RSS reader and personal knowledge management tool with MCP server integration for AI assistant connectivity.

View details
80
Repo Health
75
Technical
69
Dependency
Built with
Python 56%
TypeScript 41%
Updated 1 weeks ago
TypeScript
62%
EPL-2.0

Huly Platform

Collaboration · Project Management · Team Chat

28,064

Open-source all-in-one workspace that replaces Linear, Jira, Slack, and Notion for product and engineering teams.

View details
92
Repo Health
86
Technical
62
Dependency
Built with
TypeScript 62%
Svelte 34%
Updated 1 weeks ago
Python
51%
AGPL 3.0

Khoj

AI Assistants · Knowledge Management · Productivity

38,030

A self-hostable AI second brain that chats with your documents, searches the web, builds custom agents, and runs entirely on your own LLM.

View details
57
Repo Health
82
Technical
66
Dependency
Built with
Python 51%
TypeScript 36%
Updated 3 months ago
Go
97%
Apache 2.0

kopia

File Storage

14,598

Fast, encrypted, deduplicated backups to any cloud or local storage with full client-side control.

View details
90
Repo Health
83
Technical
68
Dependency
Built with
Go 97%
Updated 1 weeks ago
TypeScript
98%
Other

LobeHub

AI Assistants · Automation · Productivity

84,253

Your Chief Agent Operator — build, schedule, and collaborate with an entire AI team in one self-hostable workspace.

View details
92
Repo Health
81
Technical
66
Dependency
Built with
TypeScript 98%
Updated 1 weeks ago

Join founders buildingwith open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on Substack
Join 750+ subscribers