electron-store

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.