node-wifi-plus

Advanced WiFi manager for Node.js built on top of node-wifi.

It adds a clean EventEmitter API, auto-reconnect, signal monitoring, useful utilities, Promise support, and forced fresh scans (the main fix for stale network lists).

What's new in 1.1.0

Fixed: Stale / cached scan results

Previously scan() could return an old list of networks because the OS (especially Windows and some Linux setups) caches scan results.

Now by default every scan() forces a real OS-level rescan:

| Platform | Method used to force scan | |----------|--------------------------------------------| | Linux | nmcli device wifi rescan (+ fallback) | | Windows | netsh wlan show networks mode=bssid | | macOS | airport -s |

You can still disable it if you want the old (faster but sometimes stale) behavior:

const wifi = new WifiPlus({ forceFreshScan: false });
// or per-call:
await wifi.scan({ force: false });

Features

| Feature | Status | Notes | |--------------------------------|--------|--------------------------------------------| | Scan networks | ✅ | Now forces real scan by default | | Connect / Disconnect | ✅ | Clean async API | | Auto-reconnect | ✅ | Optional, configurable | | Event system | ✅ | connect, disconnect, reconnect, etc. | | Signal strength monitoring | ✅ | Emits signalChange and lowSignal | | Current connection info | ✅ | SSID, signal, quality | | Wait helpers | ✅ | waitForConnection, waitForDisconnect | | Best network selection | ✅ | Connect to strongest signal | | TypeScript definitions | ✅ | Full .d.ts included | | Cross-platform | ✅ | Windows, macOS, Linux (via node-wifi) |

Installation

npm install node-wifi-plus

Quick Start

const WifiPlus = require('node-wifi-plus');

const wifi = new WifiPlus({
  iface: null,           // auto-detect interface
  autoReconnect: true,
  watchInterval: 4000,
  forceFreshScan: true,  // default – always get fresh networks
  debug: false
});

// Listen to events
wifi.on('connect', (network) => {
  console.log('Connected to:', network.ssid);
});

wifi.on('disconnect', () => {
  console.log('Disconnected');
});

wifi.on('networkChange', (network) => {
  console.log('Switched to:', network.ssid);
});

wifi.on('lowSignal', (network) => {
  console.log('Weak signal on', network.ssid, network.signal_level, 'dBm');
});

wifi.on('error', (err) => {
  console.error('WiFi error:', err.message);
});

// Use the API
(async () => {
  // This now forces a real scan every time
  const networks = await wifi.scan();
  console.log('Found networks:', networks.length);

  // await wifi.connect('MyNetwork', 'password123');
  // const current = await wifi.getCurrentConnection();
})();

Constructor Options

new WifiPlus({
  iface: null,                 // Network interface (null = auto)
  autoReconnect: false,        // Automatically reconnect on drop
  watchInterval: 4000,         // Status check interval (ms)
  lowSignalThreshold: -75,     // dBm threshold for lowSignal event
  forceFreshScan: true,        // Force real OS scan on every scan() (recommended)
  debug: false                 // Enable debug logs
});

scan() options

// Force a fresh scan (default)
const networks = await wifi.scan();
const networks = await wifi.scan({ force: true });

// Skip force-rescan (faster, may return cached data)
const networks = await wifi.scan({ force: false });

Events

| Event | Description | Payload | |------------------|------------------------------------------|----------------------------------| | connect | Successfully connected | network | | disconnect | Disconnected | — | | reconnect | Auto-reconnected | network | | networkChange | Connected network changed | network | | scan | Scan finished | networks[] | | scanning | Scan started | — | | status | Periodic status update | { connected, network, signal } | | signalChange | Signal changed significantly | { oldSignal, newSignal, network } | | lowSignal | Signal dropped below threshold | network | | error | Any error | Error |

Notes & Limitations

• This module is a high-level wrapper around node-wifi.
• Forced scan makes results much more reliable but is slightly slower (extra 0.8–1.5 s).
• Some features (especially saved network listing) depend on OS support.
• Always run with appropriate permissions (especially on Linux).
• Auto-reconnect uses the system’s saved profiles (password is not stored by this module).

License

MIT

Built with ❤️ on top of node-wifi