DylanPiercey/local-devices

🔮 Find devices connected to the current local network.

Summary

local-devices is a small JavaScript library that discovers devices on the same local network by reading the operating system's ARP table via the arp command. It actively pings every IP in the requested range first, so hosts that have not communicated recently still appear in the results, and returns each entry as a simple { name, ip, mac } object.

What it is useful for

This kind of discovery comes up whenever a Node.js tool needs to find other machines on a LAN without being given their addresses. A few realistic scenarios:

• A developer onboarding tool that lists every device currently on the office Wi-Fi so a new laptop can SSH to a test server or a shared printer.
• A home automation script that locates smart bulbs, TVs, or routers by scanning a /24 subnet like 192.168.0.0/24.
• A CI helper that wants to verify a freshly provisioned device is reachable before running integration tests.
• A small network inventory utility that records IP-to-MAC mappings for audit purposes.

The output is intentionally minimal, so it composes well with other libraries: filter for a known MAC prefix, compare against a saved list to detect new devices, or feed the IPs into another scanning tool.

How engineers can use it

The README shows the full API, which is a single find() function. Install it like any other npm package:

npm install local-devices

Basic usage from the README:

const find = require('local-devices');

find().then(devices => {
  // [{ name: '?', ip: '192.168.0.10', mac: '...' }, ...]
});

The same function accepts options:

• { address: '192.168.0.10' } to look up a single host.
• { address: '192.168.0.1-192.168.0.25' } to scan an explicit IP range.
• { address: '192.168.0.0/24' } to scan a whole subnet using CIDR notation.
• { skipNameResolution: true } to use arp -an and avoid reverse DNS lookups. The README notes this is faster but is ignored on Windows, where arp -an is not supported.
• { arpPath: '/usr/sbin/arp' } to point at a non-default location for the arp binary.

A couple of documented limitations to keep in mind. Hostnames are often unavailable and come back as '?', so production code should usually key off mac or ip. Scanning a full /24 pings 254 addresses, which can be slow and may trigger alerts on monitored networks. Because it shells out to arp, it only works where that binary exists; behavior on Windows is partially reduced. For full details and edge cases, the README on GitHub is the source of truth.