Registry / devops / node-idevice

node-idevice

JSON →
library0.1.6jsnpmunverified

node-idevice is a Node.js wrapper for the `ideviceinstaller` command-line utility, designed to programmatically manage applications on iOS devices. It allows developers to install, remove, and list applications on a connected physical iOS device. The current stable version is `0.1.6`, published in 2017, indicating it is likely abandoned and no longer actively maintained. Its release cadence was irregular prior to cessation of development. A key differentiator is its ability to integrate iOS app management directly into Node.js workflows, such as CI/CD pipelines or automated testing setups, leveraging the robust `libimobiledevice` ecosystem. However, it relies heavily on the `ideviceinstaller` binary being pre-installed on the host system, typically via Homebrew, and exclusively uses a callback-based API, predating modern async/await patterns.

devopstesting
npm install node-idevice
package ↗
INSTALL
IMPORT
SIG · NODE-IDEVICE
N
node-idevice
devopsjavascriptv0.1.6
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

IDevice
✓ const IDevice = require('node-idevice');
This package is designed for CommonJS environments due to its age (last published 2017). The primary export is the IDevice constructor.
IDevice (ESM)
✓ import IDevice from 'node-idevice';
✗ import { IDevice } from 'node-idevice';
While technically possible to import in ESM via an interop layer, `node-idevice` was written for CommonJS. If you must use ESM, treat the constructor as a default export, but compatibility with modern Node.js ESM environments is not guaranteed.
Constructor options
✓ const device = new IDevice(false, { cmd: '/path/to/ideviceinstaller' });
The constructor allows specifying a custom path to the ideviceinstaller binary, which is useful if it's not in the system's PATH or a specific version is required.

This quickstart demonstrates how to install an IPA package on a connected iOS device, wait for the installation to complete, list all installed applications, and then remove the newly installed app. It highlights the callback-based API and the dependency on the `ideviceinstaller` binary.

const path = require('path'); const IDevice = require('node-idevice'); // --- Prerequisites --- // 1. Install ideviceinstaller via Homebrew: // brew install ideviceinstaller // 2. Connect an iOS device with developer mode enabled and 'Trust' the computer. // 3. Replace 'your-app-bundle-id' and 'path/to/your/App.ipa' with actual values. const ipaPath = path.resolve(__dirname, './path/to/your/App.ipa'); // Placeholder: replace with actual IPA path const appBundleId = 'com.example.YourApp'; // Placeholder: replace with actual app bundle ID const device = new IDevice(); // Uses ideviceinstaller from your $PATH console.log(`Attempting to install ${appBundleId} from ${ipaPath} on connected iOS device...`); device.installAndWait(ipaPath, appBundleId, function (err, success) { if (err) { console.error('Failed to install app:', err.message); if (err.message.includes('No device found')) { console.error('Please ensure an iOS device is connected, trusted, and has Developer Mode enabled.'); } else if (err.message.includes('command not found')) { console.error('Please ensure ideviceinstaller is installed and in your system PATH (e.g., via `brew install ideviceinstaller`).'); } return; } if (success) { console.log(`App ${appBundleId} installed successfully.`); // Optionally, list installed apps to verify device.listInstalled(function(listErr, data) { if (listErr) { console.error('Failed to list apps after install:', listErr.message); return; } console.log('Installed apps:', data.map(app => app.fullname)); // Remove the app for cleanup or further testing device.remove(appBundleId, function(removeErr) { if (removeErr) { console.error(`Failed to remove ${appBundleId}:`, removeErr.message); return; } console.log(`App ${appBundleId} removed successfully.`); }); }); } else { console.log(`App ${appBundleId} installation reported no success, but no error.`); } });
Debug
Known issues
breakingThis package relies on the external `ideviceinstaller` command-line utility, which is part of the `libimobiledevice` project. It must be manually installed on the host system (e.g., `brew install ideviceinstaller` on macOS) and be available in the system's PATH or specified in the constructor options. The project will not function without this binary.
fix
Install `ideviceinstaller` using your system's package manager (e.g., `brew install ideviceinstaller` on macOS) or specify its full path during `IDevice` instantiation.
affects: >=0.1.0
gotchaAs of its last update in 2017 (version 0.1.6), `node-idevice` uses a callback-based API, predating modern Node.js `Promise` and `async/await` patterns. Integrating it into modern asynchronous codebases will require manual promisification or wrapper functions.
fix
Wrap callback-based functions in `Promise` constructors or use utility libraries (e.g., `util.promisify` for Node.js built-ins, or custom wrappers) to convert them to Promise-based APIs for `async/await` usage.
affects: >=0.1.0
breakingThe functionality is dependent on the `ideviceinstaller` utility, which itself can be sensitive to iOS version changes and specific device configurations. Compatibility with very recent iOS versions (beyond iOS 10-11, given the package's age) is not guaranteed and likely requires an updated `libimobiledevice` toolchain.
fix
Ensure your `ideviceinstaller` binary is up-to-date and compatible with the target iOS device's version. You might need to build `libimobiledevice` tools from source for bleeding-edge compatibility, or consider alternative, more actively maintained tools for recent iOS versions.
affects: >=0.1.0
gotchaThe `installAndWait` method requires an accurate bundle ID (e.g., `com.example.YourApp`) for the application being installed. If this ID is incorrect or does not match the IPA's internal metadata, the callback might not trigger correctly or might report an error.
fix
Verify the `appBundleId` argument precisely matches the bundle identifier specified in the IPA's `Info.plist`. You can often inspect this by unzipping the IPA and checking the `Payload/*.app/Info.plist`.
affects: >=0.1.0
gotchaThe package interacts with physically connected iOS devices. Emulators or simulators are not supported. The device must be connected via USB, trusted by the host computer, and have Developer Mode enabled.
fix
Ensure a physical iOS device is connected, unlocked, trusted by the computer, and has Developer Mode enabled in its settings. Disconnect and reconnect the device if issues persist.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Command failed: ideviceinstaller --install /path/to/your/App.ipa /bin/sh: ideviceinstaller: command not found
The `ideviceinstaller` command-line utility is not installed or not accessible in the system's PATH.
fix
Install `ideviceinstaller` via Homebrew: `brew install ideviceinstaller`. If installed, ensure its directory is included in your system's PATH environment variable, or specify the full path to `ideviceinstaller` when instantiating `IDevice` (e.g., `new IDevice(false, { cmd: '/usr/local/bin/ideviceinstaller' })`).
Error: Command failed: ideviceinstaller --install /path/to/your/App.ipa ERROR: No device found
No compatible iOS device is connected, or the connected device is not recognized/trusted by the system.
fix
Ensure an iOS device is physically connected via USB, unlocked, has 'Trust This Computer' accepted, and Developer Mode is enabled in its settings. Try reconnecting the device or restarting the `ideviceinstaller` process.
Error: Command failed: ideviceinstaller --install /path/to/your/App.ipa ERROR: Could not install application
The IPA file is either corrupted, invalid, not signed correctly, or incompatible with the connected iOS device's architecture or iOS version.
fix
Verify the integrity of the IPA file. Ensure it's a valid, signed application package compatible with the target device's iOS version and processor architecture. Check `ideviceinstaller`'s verbose output (if available) for more specific errors. Rebuild the IPA if necessary.
Upgrade
Version history
0.1.6latest on npm
Audit
Dependencies
ideviceinstallerrequiredRuntime prerequisite; node-idevice is a wrapper around this native command-line tool. Must be installed separately.
Agent activity
13 hits · last 30 days
node
12
Resources
packagehttps://www.npmjs.com/package/node-idevice ↗
node-idevice — npm install node-idevice · libregistry