Electron OS Integration Pro

electron-os-integration-pro is a powerful Node.js module for Electron that extends the framework’s built-in OS APIs with advanced native integrations.

It provides a unified, high-level API for accessing system-level features like power management, audio, storage, displays, notifications, and hardware sensors — all with minimal boilerplate.

Developed and maintained by Fernando Martini.

🚀 Why use Electron OS Integration Pro?

Building a native-like desktop experience in Electron often requires juggling platform-specific APIs (macOS, Windows, Linux).
This module removes that complexity by offering a cross-platform abstraction layer with advanced capabilities not directly exposed by Electron.

✔️ Reduces boilerplate
✔️ Simplifies native API learning curve
✔️ Enables advanced, production-ready Electron apps

✨ Features

• ⚡ Power Management – Monitor detailed battery status & prevent sleep during critical tasks.
• ☁️ Storage & Cloud – Detect local sync folders for iCloud, OneDrive, Google Drive & watch directories natively.
• 🔊 System Audio – Get/set system volume, mute state & default output device.
• 🖥️ Display Control – Control brightness, check HDR mode & display support.
• 🔔 Rich Notifications – Interactive notifications with buttons & input fields.
• 💡 Hardware Sensors – Access ambient light sensor (where supported).

📦 Installation

npm install electron-os-integration-pro

⚠️ Note: This package uses native C++ addons. You’ll need a build environment:

• Node.js & npm
• node-gyp
• Python (2.7 or >=3.6)
• C++ compiler (MSVC on Windows, GCC/Clang on Linux/macOS)

⚡ Quick Start

const { app } = require('electron');
const os = require('electron-os-integration-pro');

app.whenReady().then(async () => {
  try {
    const batteryState = await os.power.getBatteryState();
    console.log(`Battery: ${batteryState.percentage}% (Charging: ${batteryState.isCharging})`);
  } catch (err) {
    console.error('Battery check failed:', err.message);
  }

  if (os.audio.isAudioSupported()) {
    await os.audio.setSystemVolume(0.5);
    console.log('System volume set to 50%.');
  }
});

📖 API Reference

The API is organized into modules:

• os.power → Battery & sleep control
• os.storage → Cloud services & file watching
• os.audio → System volume & devices
• os.display → Brightness & HDR
• os.notifications → Interactive native notifications
• os.sensors → Hardware sensors

os.power

getBatteryState(): Promise<object>

Returns the current battery status.
Returns: Promise<object>

• percentage: number (0–100)
• isCharging: boolean
• error?: string (if no battery is found)

preventSystemSleep(reason: string): number | null

Prevents the system from entering idle sleep and returns a blocker ID.

• reason: Description shown in macOS Activity Monitor.

allowSystemSleep()

Releases the sleep blocker, allowing normal sleep.

os.storage

getCloudServices(): Promise<object[]>

Detects installed cloud storage providers.
Returns: Promise<object[]> with:

• name: string (e.g., "iCloud Drive", "OneDrive")
• path: string (absolute local sync folder)
• isAvailable: boolean

watchDirectory(path: string, callback: (eventType, filePath) => void): { stop: () => void }

Watches a directory for changes.

• path: Absolute directory path.
• callback: Called with eventType ('added', 'removed', 'modified', etc.) and filePath.
  Returns: A watcher object with stop().

os.audio

isAudioSupported(): boolean

Whether the audio module is supported on the current platform.

getSystemVolume(): Promise<number>

Gets the master system volume.
Returns: Promise<number> (0.0–1.0).

setSystemVolume(level: number): Promise<void>

Sets the master system volume.

• level: number (0.0–1.0).

isSystemMuted(): Promise<boolean>

Whether the system audio is muted.

getDefaultOutputDevice(): Promise<string>

Gets the name of the default audio output device.

os.display

isDisplaySupported(): boolean

Whether the display module is supported on the current platform.

getBrightness(): Promise<number>

Gets the main display brightness.
Returns: Promise<number> (0.0–1.0).

setBrightness(level: number): Promise<void>

Sets the main display brightness.

• level: number (0.0–1.0).

isHDRActive(): Promise<boolean>

Checks if the main display is in HDR mode.

os.notifications

A singleton EventEmitter instance for interactive notifications.

isSupported(): boolean

Whether rich notifications are supported.

initialize(appId?: string)

Initializes the notification system (call once).

• appId: Windows only – AppUserModelID (AUMID).

send(options: { id: string; title: string; body: string; })

Sends a notification.

Event: 'action' – fired on user interaction.
Callback:

{
  notificationId: string;
  actionId: string;     // e.g. 'reply'
  responseText?: string // if input action
}

Example

os.notifications.initialize('Your.App.ID');

os.notifications.on('action', (data) => {
  console.log(`User clicked '${data.actionId}' on '${data.notificationId}'`);
  if (data.responseText) console.log(`User replied: ${data.responseText}`);
});

os.notifications.send({
  id: 'welcome-notif',
  title: 'Welcome!',
  body: 'Click a button to interact.'
});

os.sensors

isSupported(): boolean

Whether the sensors module is supported.

getAmbientLightSensorValue(): Promise<{ value: number; unit: 'lux' | 'raw'; }>

Reads the ambient light sensor.
Returns:

• value: number
• unit: 'lux' | 'raw'

🖥️ Platform Support

Notes: Linux support for audio/brightness/notifications depends on distribution, drivers and desktop environment.

🛠️ Troubleshooting

• Build fails on Windows → Ensure Visual Studio Build Tools and Python are installed.
• Permission errors on macOS → System Settings → Privacy & Security → grant access.
• Notifications missing on Windows → Set a valid AppUserModelID via notifications.initialize(appId).

🤝 Contributing

1. Fork the repo
2. Create a branch: git checkout -b feat/my-feature
3. Commit and push
4. Open a Pull Request 🚀

📄 License

MIT – free for personal and commercial use.