Registry / http-networking / expo-http-server

expo-http-server

library0.1.13jsnpmunverified

expo-http-server is an Expo module that provides a simple HTTP server implementation exclusively for iOS and Android React Native applications. It is currently at version 0.1.13 and sees active development with recent updates for Expo 53 compatibility and feature enhancements like custom headers. The module leverages native libraries, Criollo for iOS and AndroidServer for Android, offering local network communication capabilities directly from the mobile device. A key differentiator is its focus on embedding a server within a mobile app, enabling scenarios like local API mocking, inter-app communication, or serving local assets without a remote backend. It notably does not support web environments, which is a crucial limitation to understand.

http-networking web-framework

npm install expo-http-server

github ↗package ↗

INSTALL

IMPORT

SIG · EXPO-HTTP-SERVER

expo-http-server

http-networkingjavascriptv0.1.13

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

* as server

✓ import * as server from 'expo-http-server';

✗ const server = require('expo-http-server');

The module is primarily designed for modern JavaScript/TypeScript environments in Expo, favoring ESM imports.

StatusEvent

✓ import type { StatusEvent } from 'expo-http-server';

Type import for handling server status events, essential for TypeScript projects.

Request

✓ import type { Request } from 'expo-http-server';

Type import for the request object passed to route handlers, useful for type safety.

This example demonstrates how to set up an HTTP server on port 9666, define two routes ('/' and '/html'), and handle incoming GET requests to serve JSON and HTML content, respectively, within an Expo React Native app.

import * as server from 'expo-http-server'; import { useEffect, useState } from 'react'; import { Text, View } from 'react-native'; export default function App() { const [lastCalled, setLastCalled] = useState<number | undefined>(); const html = ` <!DOCTYPE html> <html> <body style="background-color:powderblue;"> <h1>expo-http-server</h1> <p>You can load HTML!</p> </body> </html>`; const obj = { app: 'expo-http-server', desc: 'You can load JSON!' }; useEffect(() => { server.setup(9666, (event: server.StatusEvent) => { if (event.status === 'ERROR') { console.error('Server error:', event.message); } else { console.log('Server status:', event.status); } }); server.route('/', 'GET', async (request) => { console.log('Request to / (GET)', request); setLastCalled(Date.now()); return { statusCode: 200, headers: { 'Custom-Header': 'Bazinga', }, contentType: 'application/json', body: JSON.stringify(obj), }; }); server.route('/html', 'GET', async (request) => { console.log('Request to /html (GET)', request); setLastCalled(Date.now()); return { statusCode: 200, statusDescription: 'OK - CUSTOM STATUS', contentType: 'text/html', body: html, }; }); server.start(); return () => { server.stop(); }; }, []); return ( <View style={{ flex: 1, backgroundColor: '#fff', alignItems: 'center', justifyContent: 'center', }} > <Text> {lastCalled === undefined ? 'Request webserver to change text' : 'Called at ' + new Date(lastCalled).toLocaleString()} </Text> </View> ); }

Debug

Known issues

breakingThe internal mechanism for matching callbacks changed from relying solely on path and method to using a UUID. This might affect advanced use cases or debugging if prior versions were implicitly relying on specific routing implementation details.

fix

Review existing route definitions and ensure they are compatible with the updated callback matching logic. If you were relying on implicit behavior of route matching, re-test thoroughly.

affects: >=0.1.10

breakingFor iOS, the body of incoming requests is now consistently sent as a JSON string. This changes the expected format for request body parsing on the server side.

fix

Ensure your request handlers for iOS properly parse JSON strings for the request body. If you were expecting a different format, adjust your parsing logic accordingly.

affects: >=0.1.3

gotchaThe server does not support web environments. It is strictly for iOS and Android React Native applications.

fix

Do not attempt to use this module in a web browser environment. Implement conditional logic if your project targets multiple platforms, including web.

affects: >=0.1.0

gotchaOn iOS, when the app is backgrounded, the HTTP server will inevitably pause after approximately 25 seconds due to operating system limitations, even with background tasks. The server will resume when the app returns to the foreground.

fix

Design your application with the expectation that the server may pause on iOS when in the background. Inform users of this limitation. For persistent background operation on Android, consider implementing a foreground service, possibly with a library like Notifee.

affects: >=0.1.0

gotchaRunning an HTTP server directly on a mobile device introduces potential security considerations. Ensure proper access control, input validation, and avoid exposing sensitive data or functionality without strong authentication.

fix

Implement robust security practices. Limit access to trusted networks/devices if possible. Validate all incoming requests. Avoid exposing administrative endpoints or sensitive data. Consider using HTTPS if sensitive data is involved, though this module might not directly support it out-of-the-box.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: server.start is not a function

The module was either not imported correctly (e.g., using CommonJS require in a modern Expo setup) or the application is running in an unsupported environment like a web browser.

fix

Ensure you are using `import * as server from 'expo-http-server';` and verify that the application is running on an iOS or Android device/emulator, not in a web browser.

Server not starting on iOS when app is backgrounded / Server stops responding after a short time in background (iOS)

iOS operating system limitations impose strict time limits on background tasks, causing the server to pause.

fix

This is expected behavior on iOS. The server automatically pauses and resumes. For critical background operations, consider alternative inter-process communication or design patterns that do not rely on a continuously running HTTP server in the background on iOS.

TypeError: Cannot read property 'setup' of undefined in browser environment

The `expo-http-server` module does not have a web implementation and its native modules are undefined when running in a browser.

fix

This module is exclusively for iOS and Android. If your project targets web, use conditional imports or a web-specific HTTP server solution.

My route handler isn't being called / Route path doesn't seem to match

Possible issues with route definition, conflicting routes, or changes in how routes are matched internally (e.g., v0.1.10 change).

fix

Double-check the path, method, and callback definitions for `server.route()`. Ensure there are no overlapping routes. Refer to the v0.1.10 breaking change regarding UUID-based matching.

Upgrade

Version history

0.1.13latest on npm

Audit

Dependencies

exporequiredPeer dependency required for Expo module functionality.

reactrequiredPeer dependency for React Native environment.

react-nativerequiredPeer dependency for React Native environment.

Agent activity

5 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/simonsturge/expo-http-server ↗

packagehttps://www.npmjs.com/package/expo-http-server ↗