{"id":11430,"library":"node-idevice","title":"node-idevice: iOS App Management","description":"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.","status":"abandoned","version":"0.1.6","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","ios","install","device","ideviceinstaller"],"install":[{"cmd":"npm install node-idevice","lang":"bash","label":"npm"},{"cmd":"yarn add node-idevice","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-idevice","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime prerequisite; node-idevice is a wrapper around this native command-line tool. Must be installed separately.","package":"ideviceinstaller","optional":false}],"imports":[{"note":"This package is designed for CommonJS environments due to its age (last published 2017). The primary export is the IDevice constructor.","symbol":"IDevice","correct":"const IDevice = require('node-idevice');"},{"note":"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.","wrong":"import { IDevice } from 'node-idevice';","symbol":"IDevice (ESM)","correct":"import IDevice from 'node-idevice';"},{"note":"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.","symbol":"Constructor options","correct":"const device = new IDevice(false, { cmd: '/path/to/ideviceinstaller' });"}],"quickstart":{"code":"const path = require('path');\nconst IDevice = require('node-idevice');\n\n// --- Prerequisites ---\n// 1. Install ideviceinstaller via Homebrew:\n//    brew install ideviceinstaller\n// 2. Connect an iOS device with developer mode enabled and 'Trust' the computer.\n// 3. Replace 'your-app-bundle-id' and 'path/to/your/App.ipa' with actual values.\n\nconst ipaPath = path.resolve(__dirname, './path/to/your/App.ipa'); // Placeholder: replace with actual IPA path\nconst appBundleId = 'com.example.YourApp'; // Placeholder: replace with actual app bundle ID\n\nconst device = new IDevice(); // Uses ideviceinstaller from your $PATH\n\nconsole.log(`Attempting to install ${appBundleId} from ${ipaPath} on connected iOS device...`);\n\ndevice.installAndWait(ipaPath, appBundleId, function (err, success) {\n  if (err) {\n    console.error('Failed to install app:', err.message);\n    if (err.message.includes('No device found')) {\n        console.error('Please ensure an iOS device is connected, trusted, and has Developer Mode enabled.');\n    } else if (err.message.includes('command not found')) {\n        console.error('Please ensure ideviceinstaller is installed and in your system PATH (e.g., via `brew install ideviceinstaller`).');\n    }\n    return;\n  }\n\n  if (success) {\n    console.log(`App ${appBundleId} installed successfully.`);\n    // Optionally, list installed apps to verify\n    device.listInstalled(function(listErr, data) {\n        if (listErr) {\n            console.error('Failed to list apps after install:', listErr.message);\n            return;\n        }\n        console.log('Installed apps:', data.map(app => app.fullname));\n        // Remove the app for cleanup or further testing\n        device.remove(appBundleId, function(removeErr) {\n            if (removeErr) {\n                console.error(`Failed to remove ${appBundleId}:`, removeErr.message);\n                return;\n            }\n            console.log(`App ${appBundleId} removed successfully.`);\n        });\n    });\n  } else {\n    console.log(`App ${appBundleId} installation reported no success, but no error.`);\n  }\n});\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Install `ideviceinstaller` using your system's package manager (e.g., `brew install ideviceinstaller` on macOS) or specify its full path during `IDevice` instantiation.","message":"This 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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"As 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=0.1.0"},{"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`.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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' })`).","cause":"The `ideviceinstaller` command-line utility is not installed or not accessible in the system's PATH.","error":"Error: Command failed: ideviceinstaller --install /path/to/your/App.ipa\n/bin/sh: ideviceinstaller: command not found"},{"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.","cause":"No compatible iOS device is connected, or the connected device is not recognized/trusted by the system.","error":"Error: Command failed: ideviceinstaller --install /path/to/your/App.ipa\nERROR: No device found"},{"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.","cause":"The IPA file is either corrupted, invalid, not signed correctly, or incompatible with the connected iOS device's architecture or iOS version.","error":"Error: Command failed: ideviceinstaller --install /path/to/your/App.ipa\nERROR: Could not install application"}],"ecosystem":"npm"}