@devioarts/capacitor-tcpclient

TCP client plugin for Capacitor apps with native Android, iOS and Electron support.

Use it when your app needs to talk to a TCP device or service directly, for example printers, scanners, controllers, gateways or local network hardware.

Features

• Native TCP sockets on Android, iOS and Electron
• Multi-connection API with isolated listeners per connection
• Raw writes, continuous stream reads and request/response reads
• Byte payloads as number[] or Uint8Array
• Optional expect pattern matching for protocol replies
• Web stub for browser development builds

Install

npm install @devioarts/capacitor-tcpclient
npx cap sync

Android network permissions are merged automatically from the plugin manifest. See Getting started for manual Android fallback notes and the required iOS setup.

Quick Start

import { TCPClient } from '@devioarts/capacitor-tcpclient';

const conn = TCPClient.createConnection({
  host: '192.168.1.100',
  port: 9100,
  timeout: 3000,
});

await conn.connect();

const reply = await conn.writeAndRead({
  data: [0x1b, 0x40],
  timeout: 1000,
  maxBytes: 4096,
});

if (reply.error) {
  console.error(reply.errorMessage);
} else {
  console.log('Received bytes:', reply.data);
}

await conn.destroy();

Capacitor App Example

import { TCPClient, type TCPConnection } from '@devioarts/capacitor-tcpclient';

let connection: TCPConnection | undefined;

export async function connectToDevice(host: string) {
  connection = TCPClient.createConnection({ connectionId: 'main-device', host, port: 9100 });

  await connection.addListener('tcpDisconnect', ({ reason, error }) => {
    console.log('TCP disconnected:', reason, error ?? '');
  });

  return connection.connect();
}

export async function sendCommand(command: Uint8Array) {
  if (!connection) throw new Error('TCP connection is not ready');

  return connection.writeAndRead({
    data: command,
    expect: '0d0a',
    timeout: 1500,
    maxBytes: 8192,
  });
}

export async function disconnectFromDevice() {
  await connection?.destroy();
  connection = undefined;
}

Documentation

• Getting started: installation, Android/iOS setup and playground notes
• Usage guide: Capacitor examples, streaming, request/response and lifecycle patterns
• Electron integration: Capacitor Electron and manual Electron bridge setup
• Behavior and FAQ: timeouts, buffering, platform notes and troubleshooting
• API reference: generated TypeScript API reference in this README

Platform Support

Common Commands

npm run build
npm test
npm run verify:web

API

The generated API below documents the root @devioarts/capacitor-tcpclient entry point used by Capacitor apps. The manual Electron bridge exposes the native methods directly over IPC, so it uses connectionId on every call instead of createConnection().

• createConnection(...)
• getPluginPlatform()
• Interfaces
• Type Aliases

createConnection(...)

createConnection(options?: TcpCreateConnectionOptions | undefined) => TCPConnection

Create (or retrieve) a TCP connection instance.

• Without connectionId: always creates a new instance with a generated UUID.
• With connectionId: returns the existing instance if one was already created, otherwise creates a new one.
• host/port/timeout/noDelay/keepAlive supplied here become defaults for connect().

Returns: TCPConnection

getPluginPlatform()

getPluginPlatform() => Promise<TcpGetPlatformResult>

Returns the platform identifier for this plugin's native implementation ('ios' | 'android' | 'electron' | 'web').

Distinct from the Capacitor core Capacitor.getPlatform() — use this when you need to know whether the TCP layer is backed by iOS, Android, Electron, or the browser development stub.

Returns: Promise<TcpGetPlatformResult>

Interfaces

TCPConnection

A single TCP connection instance returned by TCPClient.createConnection(). Each instance has its own socket, event listeners, and lifecycle.

TcpConnectResult

TcpConnectOptions

TcpDisconnectResult

TcpIsConnectedResult

TcpIsReadingResult

TcpWriteResult

TcpWriteOptions

TcpByteArrayLike

Byte-like array accepted by write APIs. Uint8Array is supported because it has numeric indexes and a length.

TcpWriteAndReadResult

TcpWriteAndReadOptions

TcpStartStopResult

TcpStartReadOptions

PluginListenerHandle

TcpDataEvent

Emitted by the stream reader. connectionId identifies which connection sent the data.

TcpDisconnectEvent

Emitted when a connection closes.

TcpCreateConnectionOptions

Options for TCPClient.createConnection(). All fields are optional. host/port and other connect options set here become defaults for every connect() call on the returned instance.

TcpGetPlatformResult

Type Aliases

Partial

Make all properties in T optional

{ [P in keyof T]?: T[P]; }

TcpBytePayload

Byte payload accepted by write APIs. Values must be integer bytes in the 0..255 range.

number[] | TcpByteArrayLike

TcpPlatform

'ios' | 'android' | 'web' | 'electron'

License

MIT