macos-focus-manager

A native Node.js module for managing application focus and window management on macOS. Built specifically for Electron apps that need precise control over window focus and frontmost application state.

Features

• Get and set frontmost application
• Track previous application focus
• Universal binary support (x64 and arm64)
• TypeScript type definitions included
• Built for macOS 10.15 and later

Installation

npm install macos-focus-manager

Requirements

• macOS 10.15 or later
• Node.js >= 18.0.0
• Electron >= 25.0.0 (if using with Electron)

Usage

Basic Usage

import { FocusManager } from "macos-focus-manager";

// Create a new instance
const focusManager = new FocusManager();

// Get frontmost application info
const currentApp = focusManager.getFrontmostApp();
console.log("Current frontmost app:", currentApp);
// Output: { name: 'App Name', bundleId: 'com.example.app', pid: 12345 }

// Get previous application info
const prevApp = focusManager.getPreviousApp();
console.log("Previous app:", prevApp);

// Focus a specific application by PID
focusManager.focusApp(12345);

// Store current frontmost app for later restoration
focusManager.storeFrontmostApp();

Electron Integration Example

import { BrowserWindow } from "electron";
import { FocusManager } from "macos-focus-manager";

class WindowManager {
  private focusManager: FocusManager;
  private window: BrowserWindow;
  private previousApp: AppInfo | null = null;

  constructor(window: BrowserWindow) {
    this.focusManager = new FocusManager();
    this.window = window;

    // Store previous app before showing window
    window.on("show", () => {
      this.previousApp = this.focusManager.getFrontmostApp();
    });

    // Handle window blur
    window.on("blur", () => {
      if (this.previousApp) {
        this.focusManager.focusApp(this.previousApp.pid);
        this.previousApp = null;
      }
    });
  }
}

API Reference

FocusManager

Methods

• getFrontmostApp(): AppInfo | null Returns information about the currently frontmost application.

• getPreviousApp(): AppInfo | null Returns information about the previously focused application.

• focusApp(pid: number): boolean Focuses the application with the given process ID.

• storeFrontmostApp(): boolean Stores the current frontmost application for later reference.

Types

type AppInfo = {
  name: string; // Application name
  bundleId: string; // Bundle identifier
  pid: number; // Process ID
};

Building from Source

# Install dependencies
npm install

# Build the module
npm run build

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.