@mcesystems/adb-kit

ADB (Android Debug Bridge) toolkit for device management. Provides a TypeScript wrapper around adbkit for Android device operations.

Features

• Device Operations: Get device properties, install/uninstall apps
• USB Debugging Detection: Check and wait for USB debugging enabled
• Port Forwarding: Forward local ports to device services
• Cross-platform: Works on Windows, macOS, and Linux

Installation

npm install @mcesystems/adb-kit

Requirements

• Node.js 18+
• Android device with USB debugging enabled
• ADB binaries (see Platform Setup)

Platform Setup

Using the Export Script (Recommended for Distribution)

Use the export script to bundle ADB binaries for your application:

# Using npx (after installing the package)
npx export-adb-resources /path/to/your-app/resources/adb-kit

# Or export for all platforms at once
npx export-adb-resources /path/to/your-app/resources/adb-kit --all

# Or run the script directly
npx tsx node_modules/@mcesystems/adb-kit/scripts/export-resources.ts /path/to/your-app/resources

See scripts/README.md for detailed prerequisites and instructions.

Windows & macOS (Development)

Set the AdbBinPath environment variable to the ADB binary location, or ensure adb is in your system PATH.

Linux

Install ADB via your package manager:

sudo apt install adb  # Debian/Ubuntu
sudo dnf install android-tools  # Fedora

Usage

Basic Device Operations

import { AdbDeviceKit } from '@mcesystems/adb-kit';

// Create a device kit for a specific device
const device = new AdbDeviceKit('device-serial-number', 1);

// Get device properties
const [manufacturer, model] = await device.getDeviceProperties(['Manufacturer', 'Model']);
console.log(`Device: ${manufacturer} ${model}`);

// Get all properties
const allProps = await device.getAllDeviceProperties();

// List connected devices
const devices = await device.listDevices();

App Management

const device = new AdbDeviceKit('device-serial-number', 1);

// Install an APK
await device.installApp('/path/to/app.apk');

// Check if app is installed
const isInstalled = await device.isAppInstalled('com.example.app');

// Uninstall an app
await device.uninstallApp('com.example.app');

USB Debugging

const device = new AdbDeviceKit('device-serial-number', 1);

// Check if USB debugging is enabled
const hasDebugging = await device.hasUsbDebugging();

// Wait for USB debugging to be enabled (with timeout)
await device.waitForUsbDebugging(30000); // 30 seconds

Port Forwarding

const device = new AdbDeviceKit('device-serial-number', 1);

// Forward a local port to a device service
const localPort = await device.startPortForward('tcp:8080');
console.log(`Forwarded to local port: ${localPort}`);

Access ADB Client

const device = new AdbDeviceKit('device-serial-number', 1);

// Get the underlying adbkit client for advanced operations
const client = await device.getClient();

// Get the device client for direct device operations
const deviceClient = await device.getDeviceClient();

API Reference

AdbDeviceKit

Constructor:

• new AdbDeviceKit(deviceId: string, port: number): Create a device kit

Device Info:

• getDeviceId(): Get the device serial number
• getPort(): Get the logical port number
• getDeviceProperties(properties: DeviceProperty[]): Get specific device properties
• getAllDeviceProperties(): Get all device properties

Device State:

• hasUsbDebugging(): Check if USB debugging is enabled
• waitForUsbDebugging(timeout?): Wait for USB debugging

App Management:

• installApp(apkPath: string): Install an APK
• uninstallApp(packageName: string): Uninstall an app
• isAppInstalled(packageName: string): Check if app is installed

Port Forwarding:

• startPortForward(serviceName: string): Forward to a device service

Advanced:

• getClient(): Get the adbkit client
• getDeviceClient(): Get the device client
• listDevices(): List all connected devices

DeviceProperty

Available device properties:

• Manufacturer, Name, Model, Brand, Device
• Android Version, Platform, CPU, CPU.abi2
• Description, Fingerprint
• GSM Flexversion, GSM IMEI
• Locale Language, Locale Region
• Wifi Channels, Board Platform, Product Board
• Display ID, Version Incremental, Version SDK
• Version Codename, Version Release
• Build Date, Build Type, Build User

Development

# Build the package
npm run build

# Run tests
npm test

# Clean build artifacts
npm run clean

Setting Up ADB for Development

For development, you can either:

1. Use the export script to download ADB to a local path
2. Install ADB via Homebrew (brew install android-platform-tools) or your system package manager
3. Set AdbBinPath environment variable to your ADB installation

License

ISC

ADB Platform Tools are licensed under the Apache License 2.0.