aws-iot-device-sdk-js: the AWS IoT device SDK that is now security-only

Read the notice at the top before anything else

The first section of the readme is not an introduction, it is a warning, and it changes what this article can fairly say.

A new AWS IoT Device SDK is now available, in a separate repository under the research lab organisation, and it is described as a complete rework built to improve reliability, performance and security, with an invitation for feedback.

Then the line that matters for anyone considering this package: this SDK will no longer receive feature updates, but will receive security updates.

So the package is not abandoned and it is not going to break tomorrow, but it is a line that only gets fixes, and the replacement is a rewrite rather than an increment. That distinction matters for the two decisions you might be making. If you have an application already using this SDK, the commitment to security updates means you can leave it where it is, with the caveat that new AWS IoT platform features will arrive in the new package first. If you are starting something new, starting on the old line means a migration later, and the readme's own description of the successor as a complete rework suggests that migration is not small.

The rest of this article is about what the package does, because a maintained implementation with two sharp edges is a different proposition from an abandoned one.

Three classes over a well known MQTT client

The package allows developers to write JavaScript applications which access the AWS IoT Platform over MQTT or MQTT over the secure WebSocket protocol, and it can be used in Node.js environments as well as in browser applications.

It is built on top of the MQTT client for JavaScript, and it provides three classes: device, thingShadow and jobs. The device class wraps the MQTT client to provide a secure connection to the AWS IoT platform and expose the underlying client interfaces upward. The important word there is upward: you get the full client API, and the wrapper adds the things AWS IoT needs on top rather than hiding the client from you.

What the wrapper adds is the part that matters on a device with a bad network, and the readme names three features specifically. Progressive backoff retries, so a reconnecting device does not hammer the broker. Automatic re-subscription upon connection, so the topics a device subscribed to before a drop are restored without the application doing it. And queued offline publishing with a configurable drain rate, so messages published while the link is down are sent when it comes back, and the rate at which they are sent is something you choose rather than something the library picks.

That trio is the actual value of the device class over using the MQTT client directly, and it is worth checking that your application does not already reimplement any of it, because reimplementing offline queuing on top of a library that also queues is how duplicates happen.

Thing Shadows: state without a second protocol

The thingShadow class implements additional functionality for accessing Thing Shadows through the AWS IoT API, and it allows a device to update them, be notified of changes to them, get the current state of them, or delete them.

The model is a synchronised document. The readme's example is the clearest statement of the idea: a remote device can update its Thing Shadow, which allows a user to see the device's last reported state in a mobile application, and the user can also update the shadow, in which case the remote device synchronises with the new state. The device and the application never talk to each other. They both talk to the shadow.

Two implementation details are worth knowing. The class supports multiple Thing Shadows per MQTT connection, so one connection can serve several logical devices or several aspects of a device, and it allows pass-through of non-Thing-Shadow topics and MQTT events, so the same connection can carry ordinary application traffic alongside the shadow protocol. The repository has an example for that case, a thing passthrough example, alongside the plain thing example.

For a project where a device's state needs to be visible in a phone application, this is the part of the SDK that saves the most work, and it is also the part with the most subtle semantics, because you have to decide what happens when the device and the shadow disagree.

Jobs, and the agent that comes with it

The jobs class implements functionality to interact with the AWS IoT Jobs service, and the readme describes what that service is for.

The IoT Job service manages deployment of fleet-wide tasks such as device software and firmware deployments and updates, rotation of security certificates, device reboots, and custom device specific management tasks.

That list is the reason the service exists. Rotating a certificate across ten thousand devices is not something you want to do with a remote command line and a lot of patience, and the job service gives you a per-device queue of work with a way to report progress and completion.

The package includes an example agent, and the readme is careful about the two ways to use it. The agent can be used as a standalone program to manage installation and maintenance of files and other running processes, or it can be incorporated into a customized agent to meet specific application needs. The repository has both forms, a jobs agent example and a jobs example, and the example programs directory also holds device, echo and thing examples plus a temperature control example and a browser folder.

The standalone agent is the one to look at first, because it is the part you can run against a real account to see the job protocol before you build your own.

Usage metrics, and the switch that turns them off

There is a section on metrics collection, and it is one of the more interesting pieces of policy in an SDK readme.

Beginning with release 2.2.0, AWS collects usage metrics indicating which language and version of the SDK is being used. The stated reason is that this allows them to prioritise resources towards addressing issues faster in the SDKs that see the most, and the readme calls it an important data point.

The readme also acknowledges that not all customers would want to report this data by default, and that the sending of usage metrics can be easily disabled by setting the enableMetrics option to false. The option is passed in the same options object as the key path, the certificate path, the CA path, the client identifier and the host, which is the shape of the constructor for all three classes.

So the default is on, and turning it off is a single option. That is worth checking in any deployment where the device fleet is large, and it is one of the reasons to read the readme of an SDK rather than copy the example code.

The Mac keychain behaviour, which is genuinely surprising

There is a section titled for the Mac-only TLS behaviour, and it is short enough that you might scroll past it. Do not.

On a Mac, once a private key is used with a certificate, that certificate and key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically.

That is a real behavioural difference from every other platform, and it has two practical consequences. The first is that a test which expects a particular key file to be used can be surprised when the keychain returns a different one. The second is that you cannot rely on replacing the key file on disk to change what the process uses, because the keychain copy wins.

For a development team that runs the same code on several platforms, this is the kind of thing that costs a day if nobody knew, and it is exactly the sort of platform-specific caveat that belongs in a readme rather than in a support ticket.

The rest of the operational guidance is in the sections the readme points at: connection types, example programs, browser applications, troubleshooting, unit tests and a support section. The readme is a complete reference document rather than a getting started guide, which is what you would expect from a package that has been in service for years.

Installing it, and what the repository looks like

The installation is short, and there is a version floor that has been in place since the beginning.

The readme says the AWS IoT Node.js SDK will only support Node version 8.17 or above, and you can check your version with `node -v`. Installing with npm is a single command, and installing from the source repository is a clone, a change of directory and an install.

npm install aws-iot-device-sdk

git clone https://github.com/aws/aws-iot-device-sdk-js.git
cd aws-iot-device-sdk-js
npm install

The package manifest is honest about the era. The Node engine requirement is 8.17, the MQTT client is pinned to the 4.2 line, and the build tooling is Gulp 3 with a set of plugins, a linter, a style checker, a test task and a coverage task. The test runner is Mocha with Sinon and a module rewriter for testing internals. The browser build has its own script.

The repository layout matches a long-lived project: separate directories for the device, thing shadow and jobs implementations, a shared common directory, a browser variant, an examples directory, a directory of integration tests, a continuous delivery directory and a test directory, with linting configuration for two linters side by side.

The release history tells the same story as the notice at the top. Version 2.2.14 fixed region validation to allow Gov Cloud and other AWS regions, 2.2.15 followed in July 2024, and 2.2.16 is described as a test release with an ephemeral npm authentication token, published in November 2025. The last push was on 2026-07-07 with the repository not archived, so the security commitment is being kept, one fix at a time.

Editorial conclusion

aws-iot-device-sdk-js suits an existing project that already depends on it and needs to keep receiving security fixes, since that is the commitment the readme makes. It is a poor fit for a new project, because the successor package is a complete rework and starting on the old line means migrating later. Before you build anything new on it, read the notice at the top of the readme and evaluate the version 2 package instead, and if you do stay, be aware that the Mac keychain behaviour and the usage metrics switch are the two things that will surprise you.

Frequently asked questions

Official sources

1. aws/aws-iot-device-sdk-js on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases