{"id":16586,"library":"windows-foreground-love","title":"Windows Foreground Love API","description":"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.","status":"active","version":"0.6.1","language":"javascript","source_language":"en","source_url":"https://github.com/the-ress/node-windows-foreground-love","tags":["javascript","typescript"],"install":[{"cmd":"npm install windows-foreground-love","lang":"bash","label":"npm"},{"cmd":"yarn add windows-foreground-love","lang":"bash","label":"yarn"},{"cmd":"pnpm add windows-foreground-love","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the common destructuring pattern for named exports in CommonJS. The 'wrong' example would assign the entire module object instead of the function.","wrong":"const allowSetForegroundWindow = require('windows-foreground-love');","symbol":"allowSetForegroundWindow","correct":"const { allowSetForegroundWindow } = require('windows-foreground-love');"},{"note":"This exact property access pattern is demonstrated in the package's own README for CommonJS environments.","symbol":"allowSetForegroundWindow","correct":"var allowSetForegroundWindow = require('windows-foreground-love').allowSetForegroundWindow;"},{"note":"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.","wrong":"import allowSetForegroundWindow from 'windows-foreground-love';","symbol":"allowSetForegroundWindow","correct":"import { allowSetForegroundWindow } from 'windows-foreground-love';"}],"quickstart":{"code":"const { allowSetForegroundWindow } = require('windows-foreground-love');\n\n// Example: Allow the current process to set its own foreground window.\n// This is primarily for demonstrating the API, as a process usually\n// has foreground rights over its own windows.\nconst currentPid = process.pid;\nconsole.log(`Attempting to grant foreground rights for PID ${currentPid} (current process)...`);\ntry {\n  const resultCurrent = allowSetForegroundWindow(currentPid);\n  console.log(`Result for current PID (${currentPid}): ${resultCurrent}`);\n  // On non-Windows, this will return false and do nothing.\n  // On Windows, it returns true if successful.\n} catch (error) {\n  console.error(`Error granting foreground rights for current PID: ${error.message}`);\n}\n\n// Example: Allow *all* processes to set the foreground window.\n// Use with caution as this can have security implications.\nconsole.log('\\nAttempting to allow all processes to set the foreground window...');\ntry {\n  const resultAll = allowSetForegroundWindow();\n  console.log(`Result for all processes: ${resultAll}`);\n  // On non-Windows, this will return false and do nothing.\n} catch (error) {\n  console.error(`Error allowing all processes foreground rights: ${error.message}`);\n}","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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`.","severity":"gotcha","affected_versions":">=0.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Missing or improperly configured C++ build tools required by `node-gyp` for compiling native Node.js addons on Windows.","error":"`node-gyp` rebuild` or `npm install` fails with compilation errors related to C++ or Visual Studio."},{"fix":"Ensure you are accessing the `allowSetForegroundWindow` function correctly. Use `const { allowSetForegroundWindow } = require('windows-foreground-love');` or `const allowSetForegroundWindow = require('windows-foreground-love').allowSetForegroundWindow;`.","cause":"Attempting to call the module object directly, or incorrectly destructuring named exports in a CommonJS environment.","error":"TypeError: require(...) is not a function or TypeError: Cannot read properties of undefined (reading 'allowSetForegroundWindow')"}],"ecosystem":"npm"}