HAP-NodeJS: Building HomeKit Accessories in Node.js

What HAP-NodeJS actually is, and who should not use it

The README opens with a definition rather than a pitch: HAP-NodeJS is an implementation of the HomeKit Accessory Server as specified in the HomeKit Accessory Protocol, which Apple defines as part of the HomeKit Framework. The second paragraph narrows the audience. It is, in the README's words, "intended to be used as a library to easily create your own HomeKit Accessory on a Raspberry Pi, Intel Edison, or any other platform that can run Node.js".

The same paragraph contains an explicit redirect. If you are searching for a pluggable HomeKit bridge with community plugins for devices that do not speak HomeKit, the README points you at Homebridge, which it notes also uses HAP-NodeJS internally. That distinction matters more than any feature list. HAP-NodeJS is the protocol layer. Homebridge is the product built on top of it. Choosing the wrong one wastes a weekend.

There is a second boundary stated plainly in the README: HAP-NodeJS is not an Apple certified HAP implementation, since certification is only available to members of the MFi program. If your product needs the MFi badge, this library is not the path to it. The repository is also not archived, and the last push was on 2026-08-22, with v2.2.3 released the same day.

How the accessory server is put together

The repository layout tells you most of the architecture before you read a line of code. All implementation lives under src/, TypeScript is compiled by tsc into dist/, and package.json points main at dist/index.js with types at dist/index.d.ts. Consumers import the compiled output, not the sources.

The dependency list is the protocol stack in miniature. @homebridge/ciao and bonjour-hap handle discovery, which is how an iOS device finds an accessory on the local network. fast-srp-hap implements SRP, the password-authenticated key exchange used during pairing. tweetnacl supplies the cryptographic primitives, and futoin-hkdf derives keys. @homebridge/dbus-native is present for platforms where Bluetooth or system integration goes through D-Bus. None of these are incidental; they map to stages of a HAP session: advertise, pair, derive keys, then exchange encrypted characteristic reads and writes.

Definitions are generated rather than hand-written. The package exposes a generate-definitions script that runs ts-node src/lib/definitions/generate-definitions.ts, which means the service and characteristic type definitions are produced from a source of truth into TypeScript. The docs/ directory and typedoc.config.mjs feed the generated API documentation published at developers.homebridge.io/HAP-NodeJS. The README labels that documentation as work in progress, so treat the wiki as the more reliable starting point.

Installing HAP-NodeJS and pairing a first accessory

The package is published on npm as @homebridge/hap-nodejs. The README does not print an install command, but the package name and the engines field in package.json are enough to state the constraint: Node.js ^22 || ^24 || ^26. Anything older is outside the declared support range.

npm install @homebridge/hap-nodejs

The README does not walk through a first accessory. It directs readers to the wiki, specifically the Using HAP-NodeJS as a library guide and the HomeKit Terminology page, and to the separate HAP-NodeJS-examples repository. There is also a set of accessory examples in the tree at src/accessories, described as old. The honest description of the getting-started path is: install the package, read the wiki guide, then copy from the examples repository rather than from this README.

For debugging, the README links a wiki FAQ entry on enabling debug output. The library depends on the debug package, which is the conventional Node.js mechanism for namespace-scoped logging, so expect output to be gated behind a DEBUG environment variable. The specific namespace string is not given in the README; the FAQ page is where the project says to look for it. The build scripts are conventional for a TypeScript library: npm run build wipes dist and runs tsc, npm test runs jest, and npm run lint runs eslint over src/**/*.{js,ts,json}.

Where HAP-NodeJS stops being the right tool

The largest limitation is stated by the project itself and cannot be worked around in code. HAP-NodeJS is not an Apple certified HAP implementation. The README also concedes that the implementation "tries to follow the HAP specification as close as it can, but may differ in some cases". That sentence is doing real work. Behaviour that differs from the specification is exactly the class of bug that shows up as an accessory that pairs but never responds, or one that works until a firmware update on the controller side.

A second constraint is runtime. The engines field admits Node 22, 24 and 26 only. If your deployment target is an older LTS line, or a platform where you cannot control the Node version, you are outside the supported matrix and any failure is yours to diagnose.

A third is scope, and it is the one people miss. HAP-NodeJS gives you the server side of the protocol. It does not give you a plugin ecosystem, a configuration UI, or a way to wrap a device you do not control. The README sends that audience to Homebridge, and the list of projects based on HAP-NodeJS (OpenHAB-HomeKit-Bridge, homekit2mqtt, pimatic-hap, node-red-contrib-homekit, ioBroker.homekit, AccessoryServer) shows the pattern: each of those is a separate project that made its own bridging decisions on top of this library. If your goal is "my existing device in Apple Home", writing against HAP-NodeJS directly means rebuilding what one of those already did.

Homebridge versus HAP-NodeJS: the same code, different jobs

The real alternative to HAP-NodeJS is Homebridge, and the relationship is unusual: Homebridge is built on HAP-NodeJS, so this is not a choice between competing implementations of the same thing. It is a choice about which layer you want to own.

Homebridge is described in the README as a pluggable HomeKit bridge with over a thousand community driven plugins, aimed at bringing HomeKit support to devices that do not support it out of the box. Adopting Homebridge means installing a host application and configuring plugins. Adopting HAP-NodeJS means writing the accessory: defining services and characteristics, handling reads and writes, and letting the library manage discovery, pairing and encryption.

The difference in approach shows up in what breaks. With Homebridge, a misbehaving plugin is a plugin problem, and the protocol layer underneath is shared by everyone. With HAP-NodeJS, you are the one holding the protocol boundary, so pairing failures, discovery problems and characteristic semantics are your responsibility. The other projects in the README's based-on list sit between the two: they use HAP-NodeJS but ship as bridges, which is the shape most people actually want. If you are integrating a specific non-HomeKit system that already has a bridge project, adopting that bridge is less work than adopting the library it depends on.

Licence, releases and the cost of keeping up

HAP-NodeJS is Apache-2.0, declared in both the LICENSE file and the license field of package.json. Apache-2.0 is a permissive licence that includes an express patent grant, which is a meaningful difference from MIT for a project implementing a protocol stack. It is not a copyleft licence, so it does not require you to publish your accessory code. This is a description of the licence text, not legal advice; if you are shipping a product, have your own counsel read it.

The upgrade picture is visible in the release cadence. v2.2.1 and v2.2.2 both landed on 2026-08-15, and v2.2.3 on 2026-08-22. Three patch releases in eight days suggests active bug-fixing rather than a frozen library, and the last push to the repository was on 2026-08-22, so the codebase is not dormant. The npm page also carries beta and alpha dist-tags, which means prerelease builds are published alongside stable ones; pin to the stable version rather than tracking a tag.

The maintenance cost that falls on you is the transitive dependency set. Discovery, SRP, NaCl and HKDF are all third-party packages, and the library re-exports none of the responsibility for keeping them current. Because main points at dist/, you consume compiled JavaScript and type declarations, so a dependency change inside the library is invisible in your diff until something stops pairing. The npm run check script (npm install && npm outdated) is the project's own way of noticing that, and it is worth running in your own tree if you vendor or fork.

Editorial conclusion

Adopt HAP-NodeJS if you are writing a Node.js service that must appear in Apple Home as an accessory and you accept that it is not an Apple certified HAP implementation. Do not adopt it if you want a ready-made bridge with community plugins; that is Homebridge, which uses this library internally. Before writing code, read the wiki page on HomeKit Terminology and the Using HAP-NodeJS as a library guide, and check that your Node runtime matches the engines field (^22 || ^24 || ^26).

Frequently asked questions

Official sources

1. homebridge/HAP-NodeJS on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases