node-idevice: iOS App Management

Common errors

• Error: Command failed: ideviceinstaller --install /path/to/your/App.ipa
  /bin/sh: ideviceinstaller: command not found

  cause 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

  cause 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

  cause 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.

Warnings

• breaking 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.
  Fix: Install `ideviceinstaller` using your system's package manager (e.g., `brew install ideviceinstaller` on macOS) or specify its full path during `IDevice` instantiation.
• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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.
  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`.
• gotcha 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.
  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.

Install

• npm install node-idevice npm
• yarn add node-idevice yarn
• pnpm add node-idevice pnpm

Imports

• 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)
  wrong:

  import { IDevice } from 'node-idevice';

  correct:

  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.

Quickstart

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.`);
  }
});