Windows Foreground Love API

0.6.1 · active · verified Wed Apr 22

This package provides a Node.js API wrapper for the Windows API function `AllowSetForegroundWindow`. It enables a process to allow other specified processes, or all processes, to set its foreground window, which is critical for managing window focus behavior in desktop applications, automation scripts, or Electron projects on Windows. The current stable version is 0.6.1, with releases typically occurring as needed for bug fixes, performance enhancements, or build system updates, rather than a fixed schedule. A key differentiator is its direct implementation via Node-API, providing low-level, reliable control over Windows foreground window permissions. It's explicitly designed for the Windows environment, providing no functionality on other operating systems. The package includes comprehensive TypeScript typings, enhancing developer experience and compile-time safety for TypeScript projects.

Common errors

```
`node-gyp` rebuild` or `npm install` fails with compilation errors related to C++ or Visual Studio.
```
cause Missing or improperly configured C++ build tools required by `node-gyp` for compiling native Node.js addons on Windows.

fix Install Visual Studio Build Tools (for newer Node.js versions) or `windows-build-tools` (for older Node.js versions) to provide the necessary C++ compiler and headers. Ensure `node-gyp` is globally installed and configured correctly.
```
TypeError: require(...) is not a function or TypeError: Cannot read properties of undefined (reading 'allowSetForegroundWindow')
```
cause Attempting to call the module object directly, or incorrectly destructuring named exports in a CommonJS environment.

fix Ensure you are accessing the `allowSetForegroundWindow` function correctly. Use `const { allowSetForegroundWindow } = require('windows-foreground-love');` or `const allowSetForegroundWindow = require('windows-foreground-love').allowSetForegroundWindow;`.

Warnings

gotcha The `windows-foreground-love` package is fundamentally designed for Windows operating systems. While it can be installed on other platforms, its core `allowSetForegroundWindow` function will not perform any action and will consistently return `false`.
Fix: Ensure the application using this package runs exclusively on Windows when foreground window control is required. Implement platform checks if cross-platform support is necessary for other features.
gotcha Installation on Windows requires `node-gyp` and a compatible C++ toolchain (e.g., Visual Studio Build Tools). Without these, `npm install` will fail during the native module compilation phase.
Fix: Install `node-gyp` globally (`npm install -g node-gyp`) and ensure you have the necessary build tools for your Node.js version, typically by running `npm install --global windows-build-tools` (for older Node versions) or installing Visual Studio Build Tools with the 'Desktop development with C++' workload for newer versions.
gotcha Calling `allowSetForegroundWindow()` without a `pid` (i.e., `allowSetForegroundWindow()`) grants permission for *all* processes to set the foreground window. This is a very broad permission and should be used with extreme caution due to potential security implications and unexpected application behavior.
Fix: Always specify a `pid` if you only intend to grant foreground rights to a particular process. Only use the parameter-less call if you fully understand and accept the global impact.

Install

npm install windows-foreground-love npm
yarn add windows-foreground-love yarn
pnpm add windows-foreground-love pnpm

Imports

allowSetForegroundWindow
wrong:
```
const allowSetForegroundWindow = require('windows-foreground-love');
```
correct:
```
const { allowSetForegroundWindow } = require('windows-foreground-love');
```
This is the common destructuring pattern for named exports in CommonJS. The 'wrong' example would assign the entire module object instead of the function.
allowSetForegroundWindow
```
var allowSetForegroundWindow = require('windows-foreground-love').allowSetForegroundWindow;
```
This exact property access pattern is demonstrated in the package's own README for CommonJS environments.
allowSetForegroundWindow
wrong:
```
import allowSetForegroundWindow from 'windows-foreground-love';
```
correct:
```
import { allowSetForegroundWindow } from 'windows-foreground-love';
```
Requires a Node.js ESM environment (e.g., 'type': 'module' in package.json or .mjs file extension). The package ships TypeScript types for this usage, but it is not a default export.

Quickstart

This code snippet demonstrates how to use `windows-foreground-love` to grant foreground activation permission, both for a specific process (the current one) and globally for all processes, highlighting its Windows-specific behavior.

const { allowSetForegroundWindow } = require('windows-foreground-love');

// Example: Allow the current process to set its own foreground window.
// This is primarily for demonstrating the API, as a process usually
// has foreground rights over its own windows.
const currentPid = process.pid;
console.log(`Attempting to grant foreground rights for PID ${currentPid} (current process)...`);
try {
  const resultCurrent = allowSetForegroundWindow(currentPid);
  console.log(`Result for current PID (${currentPid}): ${resultCurrent}`);
  // On non-Windows, this will return false and do nothing.
  // On Windows, it returns true if successful.
} catch (error) {
  console.error(`Error granting foreground rights for current PID: ${error.message}`);
}

// Example: Allow *all* processes to set the foreground window.
// Use with caution as this can have security implications.
console.log('\nAttempting to allow all processes to set the foreground window...');
try {
  const resultAll = allowSetForegroundWindow();
  console.log(`Result for all processes: ${resultAll}`);
  // On non-Windows, this will return false and do nothing.
} catch (error) {
  console.error(`Error allowing all processes foreground rights: ${error.message}`);
}

view raw JSON →