Electron Preferences

A simple, powerful preference management system for Electron applications with a built-in GUI

Overview

Electron Preferences provides developers with a complete preference management solution:

• Key/Value Store - Simple API for reading and writing preferences
• Built-in GUI - Customizable preferences window with React components
• 15+ Field Types - Text, numbers, dropdowns, sliders, color pickers, file selectors, and more
• Flexible Layout - Side-by-side fields, custom widths, conditional visibility
• Theme Support - Automatic dark/light mode support
• 65+ Icons - Built-in icon set plus custom SVG support
• Encrypted Storage - Secure storage for sensitive data using Electron's safeStorage

Fork Information

This is an enhanced fork of electron-preferences with additional features:

• ✨ New map field type for key-value pairs
• 🎨 Enhanced theme support (dark/light/custom)
• 🔄 Runtime section updates without reopening window
• 🎯 Flexible field layouts with custom widths
• 🖼️ Custom SVG icon support
• 📦 Additional built-in icons

Originally enhanced for the BrightScript Simulator project.

Quick Start

Installation

npm install @lvcabral/electron-preferences

Basic Usage

const { app } = require('electron');
const path = require('path');
const ElectronPreferences = require('@lvcabral/electron-preferences');

const preferences = new ElectronPreferences({
  config: {
    dataStore: path.join(app.getPath('userData'), 'preferences.json')
  },
  defaults: {
    general: {
      name: 'John Doe',
      theme: 'dark'
    }
  },
  sections: [
    {
      id: 'general',
      label: 'General',
      icon: 'settings-gear-63',
      form: {
        groups: [
          {
            label: 'User Settings',
            fields: [
              {
                label: 'Name',
                key: 'name',
                type: 'text',
                help: 'Your display name'
              },
              {
                label: 'Theme',
                key: 'theme',
                type: 'radio',
                options: [
                  { label: 'Light', value: 'light' },
                  { label: 'Dark', value: 'dark' }
                ]
              }
            ]
          }
        ]
      }
    }
  ]
});

// Show preferences window
preferences.show();

// Get/set values
const name = preferences.value('general.name');
preferences.value('general.theme', 'dark');

// Listen to changes
preferences.on('save', (prefs) => {
  console.log('Preferences updated:', prefs);
});

Documentation

Comprehensive documentation is organized into focused guides:

📚 Core Documentation

• API Reference - Complete API documentation including constructor options, methods, and events
• Field Types - All 15 field types with properties and examples
• Examples - Complete examples and common patterns
• Icons Gallery - All 65 built-in icons and custom icon usage

🚀 Key Features

Field Types

15 built-in field types for every need:

| Type | Description | |------|-------------| | text, number | Text and numeric inputs | | dropdown, radio, checkbox | Selection controls | | slider, color | Visual pickers | | file, directory | File system selection | | accelerator | Keyboard shortcut input | | list, map | Dynamic collections | | button, message | Actions and info displays | | secret | Encrypted storage |

→ See all field types with examples

Flexible Layouts

Create custom layouts with side-by-side fields:

fields: [
  {
    label: 'First Name',
    key: 'firstName',
    type: 'text',
    style: { width: '50%' }  // Side-by-side
  },
  {
    label: 'Last Name',
    key: 'lastName',
    type: 'text',
    style: { width: '50%' }
  }
]

Conditional Visibility

Show/hide sections, groups, or fields dynamically:

{
  label: 'Advanced Settings',
  hideFunction: (prefs) => !prefs.general?.showAdvanced,
  fields: [/* ... */]
}

Runtime Updates

Update UI without closing the preferences window:

const section = preferences.options.sections.find(s => s.id === 'devices');
section.form.groups[0].fields[0].options = getNewOptions();
preferences.broadcastSections(); // Updates UI immediately

Demo Application

Run the included example to see all features:

git clone https://github.com/lvcabral/electron-preferences.git
cd electron-preferences
npm install --legacy-peer-deps
npm run build
npm run example

The example demonstrates all field types, conditional visibility, custom styling, and more.

Development

npm run build        # Production build
npm run build:dev    # Development build
npm run lint         # Run ESLint
npm run example      # Run example app

Browser Window Customization

Customize the preferences window appearance:

browserWindowOverrides: {
  title: 'My App Settings',
  width: 1000,
  height: 800,
  resizable: true,
  maximizable: false
}

→ See complete configuration options

Renderer Process Integration

Access preferences from renderer processes:

const { ipcRenderer } = require('electron');

// Get preferences
const prefs = ipcRenderer.sendSync('getPreferences');

// Show preferences window
ipcRenderer.send('showPreferences');

// Listen for updates
ipcRenderer.on('preferencesUpdated', (event, prefs) => {
  console.log('Updated:', prefs);
});

→ See complete renderer API

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT License - see LICENSE file for details

Links

• GitHub Repository
• npm Package
• Original Project