Application Preferences

The prefs service provides a persistent key-value store for application preferences. Preferences are kept in an in-memory cache during the session and written to prefs.json in the application data directory when you call persist().

Overview 

The prefs service supports five value types: number, boolean, string, object, and array. Each type has a matching set of get*, set*, and has* methods.

Each getter returns the type’s zero value when the key is missing or holds a value of a different type: 0 for numbers, false for booleans, '' for strings, {} for objects, and [] for arrays. Pass an optional second argument to return a custom default instead.

Objects and arrays must contain only JSON-compatible primitives, nested arrays, and plain objects — no functions, symbols, class instances, or cyclic references. Nesting is supported up to 20 levels deep. A write that violates these constraints is silently skipped.

Storing preferences 

Use the typed setters to store a preference value under a string key. Keys can use dot-notation to express hierarchy, such as editor.fontSize or ui.sidebar.visible.

import { prefs } from '@mobrowser/api';

// Store the prefs as primitive values.
prefs.setString('ui.theme', 'dark')
prefs.setNumber('editor.fontSize', 14)
prefs.setBoolean('ui.sidebar.visible', true)

// Store the window state as an object.
prefs.setObject('ui.windowState', {
  x: 0, y: 0, width: 1024, height: 768
})

// Store the recent files as an array.
prefs.setArray('app.recentFiles', [
  '/home/user/doc.txt', 
  '/home/user/img.png'
])

Empty keys and non-finite numbers (NaN, Infinity) are silently ignored. For objects and arrays, the value must contain only JSON-compatible primitives, nested arrays, and plain objects — no functions, symbols, class instances, or cyclic references. Nesting is supported up to 20 levels deep. A write that violates these constraints is silently skipped.

Reading preferences 

Use the typed getters to read a stored value. Each getter returns the type’s zero value when the key is missing or holds a value of a different type: '' for strings, 0 for numbers, false for booleans, {} for objects, and [] for arrays.

const theme = prefs.getString('ui.theme')
const fontSize = prefs.getNumber('editor.fontSize')
const sidebarVisible = prefs.getBoolean('ui.sidebar.visible')
const windowState = prefs.getObject('ui.windowState')
const recentFiles = prefs.getArray('app.recentFiles')

You can pass an optional default value that is returned instead of the zero value when the key is missing or has the wrong type:

const theme = prefs.getString('ui.theme', 'light')
const fontSize = prefs.getNumber('editor.fontSize', 14)
const sidebarVisible = prefs.getBoolean('ui.sidebar.visible', true)
const windowState = prefs.getObject('ui.windowState', { 
  x: 100, y: 100, width: 800, height: 600
})
const recentFiles = prefs.getArray('app.recentFiles', [])

getObject and getArray accept an optional type parameter so the return type matches your data structure:

interface WindowState {
  x: number;
  y: number;
  width: number;
  height: number;
}

const windowState = prefs.getObject<WindowState>('ui.windowState', { 
  x: 100, y: 100, width: 800, height: 600 
})
const recentFiles = prefs.getArray<string>('app.recentFiles', [])

Checking if a preference is set 

Use the has* methods to test whether a key holds a value of the expected type before reading it. This is especially important for booleans, where the default return value of getBoolean (false) is also a valid stored value:

if (prefs.hasBoolean('ui.sidebar.visible')) {
  const sidebarVisible = prefs.getBoolean('ui.sidebar.visible')
}

The same pattern applies to all other types:

if (prefs.hasString('ui.theme')) {
  const theme = prefs.getString('ui.theme')
}

if (prefs.hasNumber('editor.fontSize')) {
  const fontSize = prefs.getNumber('editor.fontSize')
}

if (prefs.hasObject('ui.windowState')) {
  const windowState = prefs.getObject('ui.windowState')
}

if (prefs.hasArray('app.recentFiles')) {
  const recentFiles = prefs.getArray<string>('app.recentFiles')
}

Removing preferences 

To remove a single key from the in-memory cache, use remove():

prefs.remove('ui.theme')

To remove all keys at once, use clear():

prefs.clear()

Both operations affect only the in-memory cache. Call persist() afterwards to write the change to disk.

Persisting preferences 

All reads and writes operate on an in-memory cache. Changes are not saved to disk automatically — if the application exits before persist() is called, any unsaved changes are lost.

Call persist() when you want to commit the current state of the cache to disk:

import { prefs } from '@mobrowser/api';

prefs.setString('ui.theme', 'dark')
prefs.setNumber('editor.fontSize', 14)

if (!prefs.persist()) {
  console.error('Failed to save preferences')
}

persist() returns true if the preferences were saved successfully and false otherwise. It is good practice to check the return value and log or surface an error if saving fails.

Preferences are stored in prefs.json under the application user data directory.