Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Native APIs and Files

App Data, Paths and Persistent Settings

Learn where an Electron app should store settings and data, how app.getPath works, how to build a safe JSON settings store with defaults and migrations, and how to handle corruption.

Every app eventually needs to remember things: the window size, the theme, the last opened folder, a list of projects. Where you put that data matters. Write it next to your executable and it breaks on read-only installs; write it to the user's home folder and you scatter files; forget to handle a corrupt file and the app refuses to start.

Electron answers the "where" with app.getPath. This lesson explains the standard folders, then builds a small, robust settings store with defaults, validation, migration and atomic saves.

Where things live

app.getPath(name) returns a folder that already follows the platform's conventions.

JavaScript
import { app } from 'electron';

app.getPath('userData');   // per-user app data, e.g. %APPDATA%\MyApp
app.getPath('appData');    // the parent folder of every app's userData
app.getPath('documents');  // user's Documents
app.getPath('downloads');
app.getPath('temp');
app.getPath('logs');       // platform log folder for this app
app.getPath('exe');        // path of the running executable

The ones you will use constantly:

Name Use it for
userData settings, databases, caches you own, anything private to the app
documents, downloads, desktop places the user expects to find their files
temp throwaway files; the OS may clear it
logs rotating log files

The default userData is appData plus your app's name from package.json. Change the name and users silently lose their settings, because the folder changes. Pick the name once.

app.setPath('userData', somewhere) moves it, but call it before app.whenReady() and before anything uses the old folder.

During development you often want an isolated profile. Start a second copy with a different folder by calling app.setPath('userData', app.getPath('userData') + '-dev') when app.isPackaged is false. Your real settings stay untouched while you experiment.

What not to store there

userData is plain files readable by anyone using that account. Do not keep passwords or API tokens in it as text; see Safe Storage and Fuses for the encrypted option. For structured data in the thousands of records, prefer SQLite (node:sqlite in Node 24 or a native module) over one giant JSON file.

A settings store

A good store has five properties: it merges defaults so new settings appear for old users, it validates types, it migrates old formats, it saves atomically, and it survives a corrupt file. Here is a complete class, written against a folder path so it works the same in Electron and in a test.

Node.js A robust JSON settings store

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Read it top to bottom once: the invalid 'neon' theme falls back to the default, font_size is renamed by the migration, an out-of-range value is rejected before it reaches disk, and the corrupt file is moved aside instead of crashing startup.

Using it from Electron

Create the store in the main process after the app is ready and expose it through IPC, so the renderer asks rather than reads files.

JavaScript
import { app, ipcMain } from 'electron';

let settings;
app.whenReady().then(async () => {
  settings = await new SettingsStore(app.getPath('userData')).load();
  createWindow();
});

ipcMain.handle('settings:get', (_e, key) => settings.get(key));
ipcMain.handle('settings:set', (_e, key, value) => settings.set(key, value));

Because set validates the key and the value, a compromised renderer cannot write arbitrary keys. Libraries like electron-store and conf implement the same ideas with JSON Schema if you would rather not write your own.

Remembering the window

The most common use of settings is the window bounds. Save them on close (or debounced resize and move) and restore them on start. Remember to check that the saved position is still on a connected display; a user may unplug a monitor.

JavaScript
const { workArea } = screen.getPrimaryDisplay();
const b = settings.get('bounds');
const visible = screen.getAllDisplays().some(({ bounds: d }) =>
  b.x >= d.x && b.y >= d.y && b.x + b.width <= d.x + d.width && b.y + b.height <= d.y + d.height);
const win = new BrowserWindow(visible ? b : { width: 900, height: 700 });

A tiny debouncer for noisy events

Resize fires dozens of times a second. Writing the file each time is wasteful. A debounce delays the write until the events stop.

Node.js Debouncing frequent saves

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which path is the right home for an app's private settings?

    userData is per user, writable, and survives updates. temp may be cleared, the install folder can be read-only, and the desktop is for the user's own files.
  2. 2. Why merge a DEFAULTS object when loading settings?

    An old settings file does not know about new keys. Starting from defaults and overlaying saved values keeps the app working after an update.
  3. 3. What should the app do when settings.json is corrupt?

    A crash on startup is the worst outcome. Keeping the broken file as .broken lets you or the user inspect it while the app still launches.
  4. 4. What happens to a user's settings if you rename the app in package.json?

    The default userData folder is built from the app name. A new name means a new folder, and the old one is simply left behind.

Summary

  • Use app.getPath('userData') for private data and the documents or downloads folders for user files.
  • A settings store should merge defaults, validate, migrate, write atomically and tolerate corruption.
  • Keep the store in the main process and expose get/set over validated IPC.
  • Debounce noisy saves such as window bounds, and check that saved positions are still on screen.
  • Secrets do not belong in plain JSON.

Next: Drag and Drop, File Associations and Deep Links