@cantoo/capacitor-http-server

@cantoo-scribe/capacitor-http-server

A generic Capacitor plugin that exposes a local HTTP server on iOS and Android with routing delegated to JavaScript.

The plugin has no business logic. It only handles the transport layer: it starts a listener, hands every incoming request to JavaScript via a request event, and writes back whatever JavaScript returns through respond(). This keeps your app code — authentication, routing, payloads, CORS policy — entirely in TypeScript, where it can be tested, updated from a hot-reload bundle, and shared across platforms.

Install

npm install @cantoo-scribe/capacitor-http-server
npx cap sync

Android configuration

The plugin ships all required permissions in its manifest:

• INTERNET, ACCESS_NETWORK_STATE, ACCESS_WIFI_STATE
• FOREGROUND_SERVICE and FOREGROUND_SERVICE_DATA_SYNC (API 34+)
• POST_NOTIFICATIONS (API 33+)

The server runs inside a foreground service with type dataSync, so it survives the screen being locked. On Android 13+ the system requires a visible notification, hence POST_NOTIFICATIONS. If the user declines the permission, the server still starts but the system is free to kill the process at any moment. The plugin requests the permission automatically on the first start() call.

You must supply android.notificationTitle and android.notificationText when starting the server:

await HttpServer.start({
  android: {
    notificationTitle: 'My App',
    notificationText: 'Local server is running.',
    smallIconResourceName: 'ic_notification', // res/drawable/ic_notification.png
    channelId: 'my_app_http',
    channelName: 'Local HTTP server',
  },
});

iOS configuration

Add the following keys to your app's Info.plist:

<key>NSLocalNetworkUsageDescription</key>
<string>Used to expose a local server for sharing files across devices on this network.</string>

<!-- Optional. Only needed if you broadcast your server over Bonjour. -->
<key>NSBonjourServices</key>
<array>
  <string>_myservice._tcp</string>
</array>

Without NSLocalNetworkUsageDescription, iOS 14+ silently drops every incoming connection from other devices.

Note: iOS does not allow long-running HTTP servers in background. The plugin requests a short background task on app backgrounding, then emits a server-error event with fatal: true when the window expires. Restart the server on UIApplication.didBecomeActive.

Usage

Echo server

A complete, 20-line echo server that returns exactly what it received:

import { HttpServer } from '@cantoo-scribe/capacitor-http-server';

await HttpServer.addListener('request', async (req) => {
  await HttpServer.respond({
    requestId: req.requestId,
    status: 200,
    headers: { 'content-type': req.headers['content-type'] ?? 'text/plain' },
    ...(req.bodyText !== undefined && { bodyText: req.bodyText }),
    ...(req.bodyBase64 !== undefined && { bodyBase64: req.bodyBase64 }),
    ...(req.bodyFilePath !== undefined && { bodyFilePath: req.bodyFilePath }),
  });
});

const { url } = await HttpServer.start({
  android: {
    notificationTitle: 'Echo server',
    notificationText: 'Listening for requests',
  },
});
console.log('Listening at', url);

Test it from a laptop on the same network:

curl http://<device-ip>:<port>/ -d 'hello'
# hello

Handling errors

HttpServer.addListener('server-error', ({ message, fatal }) => {
  console.warn('Server error:', message, 'fatal:', fatal);
  if (fatal) {
    // On iOS the server dies in background; restart on foreground.
  }
});

Streaming a large file out

HttpServer.addListener('request', async (req) => {
  if (req.path === '/big.bin') {
    await HttpServer.respond({
      requestId: req.requestId,
      status: 200,
      headers: { 'content-type': 'application/octet-stream' },
      bodyFilePath: '/absolute/path/to/file.bin', // streamed, no RAM spike
    });
  } else {
    await HttpServer.respond({ requestId: req.requestId, status: 404 });
  }
});

Receiving a large upload

Bodies above fileBodyThresholdBytes (default 1 MB) are streamed to a temp file managed by the plugin. JavaScript receives the absolute path via bodyFilePath and is free to move, hash, or re-stream it. The plugin deletes the temp file automatically once respond() returns.

API

• start(...)
• stop()
• respond(...)
• addListener('request', ...)
• addListener('server-error', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

start(...)

start(options?: StartOptions | undefined) => any

Start the local HTTP server. Picks a free port if port is omitted. On Android, starts a foreground service so the server survives screen lock. Throws if the server is already running with a different configuration, or if required permissions are missing.

Param	Type
options	StartOptions

Returns: any

stop()

stop() => any

Stop the server and release all resources (port, threads, temp files, service). Safe to call when already stopped.

Returns: any

respond(...)

respond(response: HttpResponse) => any

Reply to a request previously received via the request event. The plugin looks up requestId, writes the response, and cleans up any temporary body file. Calling respond twice for the same requestId is a no-op on the second call. Unanswered requests time out (504) after 60 s.

Param	Type
response	HttpResponse

Returns: any

addListener('request', ...)

addListener(eventName: 'request', listener: (event: HttpRequestEvent) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Subscribe to incoming HTTP requests. Every accepted request fires exactly one request event; JS is expected to call respond exactly once per event.

Param	Type
eventName	'request'
listener	(event: HttpRequestEvent) => void

Returns: any

addListener('server-error', ...)

addListener(eventName: 'server-error', listener: (event: ServerErrorEvent) => void) => Promise<PluginListenerHandle> & PluginListenerHandle

Subscribe to server-level errors that are not tied to a specific request (e.g. the underlying socket died, port was stolen, permission revoked). The server is considered dead when this fires with fatal: true.

Param	Type
eventName	'server-error'
listener	(event: ServerErrorEvent) => void

Returns: any

removeAllListeners()

removeAllListeners() => any

Remove every listener registered on this plugin.

Returns: any

Interfaces

StartOptions

Prop	Type	Description
port	number	If omitted or 0, the OS picks a free port in the dynamic range.
maxBodyBytes	number	Max request body size in bytes. Bodies above this return 413. Default: 50 * 1024 * 1024 (50 MB).
fileBodyThresholdBytes	number	Threshold above which the plugin stores the body in a temp file and exposes it via bodyFilePath instead of bodyBase64. Default: 1 * 1024 * 1024 (1 MB).
android	StartOptionsAndroid	Android only. Title / text / small icon used by the foreground service notification (mandatory on Android 13+). Ignored on iOS.

StartOptionsAndroid

Prop	Type	Description
notificationTitle	string	Foreground-service notification title. Required on Android 13+.
notificationText	string	Foreground-service notification body text.
smallIconResourceName	string	Android drawable resource name, e.g. "ic_notification".
channelId	string	Notification channel ID. Plugin creates the channel if missing.
channelName	string	Notification channel display name.

StartResult

Prop	Type	Description
port	number	Chosen port (same as options.port when provided).
url	string	Full URL, e.g. "http://192.168.1.42:49281". Empty string when no LAN-reachable interface was found (e.g. cellular only). The server is still listening on the port, but cannot be reached by a peer LAN device. A server-error event with fatal: false is emitted in that case so consumers can warn the user.
localIp	string	Primary LAN IPv4. Empty string when no LAN-reachable interface was found. See url.

HttpResponse

Prop	Type	Description
data	any	Additional data received with the Http response.
status	number	The status code received from the Http response.
headers	HttpHeaders	The headers received from the Http response.
url	string	The response URL received from the Http response.

HttpHeaders

HttpRequestEvent

Prop	Type	Description
requestId	string	Opaque ID. Pass back unchanged in respond.
method	HttpMethod
path	string	Decoded pathname, always starts with "/". No querystring.
query	Record<string, string>	Parsed querystring. Repeated keys keep the last value.
headers	Record<string, string>	Lower-cased header names.
clientIp	string	Remote peer IP if available (useful for logging only).
bodyText	string	Exactly one of the three body fields is set (undefined when the request has no body). The plugin picks the representation based on content type and size: - UTF-8 body with a text-like content type (text/*, application/json, application/x-www-form-urlencoded) below threshold -> bodyText - Any other body below threshold -> bodyBase64 - Body above threshold -> bodyFilePath Temp files referenced by bodyFilePath are deleted automatically once respond is called for the same requestId (or on timeout).
bodyBase64	string
bodyFilePath	string

PluginListenerHandle

Prop	Type
remove	() => any

ServerErrorEvent

Prop	Type	Description
message	string
fatal	boolean	True when the server is no longer listening and must be restarted.

Type Aliases

HttpMethod

HTTP methods that the plugin forwards to JavaScript. Any value outside this list produced by a client is still forwarded as-is (upper-cased) but typed as HttpMethod for convenience of the common cases.

'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD'

Limitations

• No HTTPS. The plugin listens on plain HTTP. Use it over a trusted LAN or add a reverse proxy if you need TLS.
• No chunked transfer encoding on the request side. Clients must send Content-Length; otherwise the server replies with 501.
• No WebSocket support (tracked separately; out of scope here).
• iOS background. The server is suspended when the app leaves the foreground. A server-error event is emitted with fatal: true.

License

MIT © Cantoo Scribe