react-native-local-server

A lightweight, zero-dependency local HTTP static file server for React Native. Built with pure native sockets (BSD sockets on iOS, Java ServerSocket on Android) — no third-party server libraries required.

Serves files from any local directory over HTTP with chunked streaming, CORS support, and built-in JSON APIs for file/directory listing.

Features

• Pure native implementation — no embedded web server dependencies
• Large file streaming — 256KB chunked transfer, handles images/videos of any size
• Cross-platform — iOS (Objective-C) and Android (Java)
• Static file serving — serves any file type with proper MIME types
• JSON API endpoints — /api/files (recursive) and /api/dir (non-recursive)
• Force download endpoint — /download/<path> with Content-Disposition: attachment
• Directory listing — auto-generated HTML index for directories
• CORS enabled — all responses include CORS headers
• WiFi IP detection — automatically detects device WiFi IP address
• Local-only mode — optionally bind to 127.0.0.1 only
• Path traversal protection — sanitizes all request paths

Installation

npm install react-native-local-server

iOS

cd ios && pod install

Android

No additional steps required. Permissions (INTERNET, ACCESS_WIFI_STATE) are declared in the library manifest and merged automatically.

Note: This library requires React Native's new architecture or the classic bridge. It does not work with Expo Go — use a development build.

Usage

Basic Server

import StaticServer from 'react-native-local-server';

// Create server on port 8080, serving files from a local directory
const server = new StaticServer(8080, '/path/to/files');

// Start the server
const url = await server.start();
console.log('Server running at:', url);
// => "http://192.168.1.10:8080"

// Stop the server
await server.stop();

Local-Only Server (127.0.0.1)

const server = new StaticServer(8080, '/path/to/files', { localOnly: true });
const url = await server.start();
// => "http://127.0.0.1:8080"

List All Files (Recursive)

const server = new StaticServer(8080, '/path/to/files');
await server.start();

const result = await server.getFiles();
console.log(result);
// {
//   success: true,
//   root: "/path/to/files",
//   server: "http://192.168.1.10:8080",
//   total: 42,
//   files: [
//     {
//       name: "photo.png",
//       path: "events/wedding/photo.png",
//       url: "http://192.168.1.10:8080/download/events/wedding/photo.png",
//       size: 1234567,
//       mime: "image/png",
//       ext: "png",
//       modified: 1708300000000
//     },
//     ...
//   ]
// }

List Directory Contents (Non-Recursive)

// List root directory
const root = await server.getDir();

// List a subdirectory
const eventDir = await server.getDir('events/wedding');
console.log(eventDir);
// {
//   success: true,
//   path: "events/wedding",
//   server: "http://192.168.1.10:8080",
//   total: 3,
//   items: [
//     { name: "photos", path: "events/wedding/photos", type: "directory", children: 24, modified: 1708300000000 },
//     { name: "cover.png", path: "events/wedding/cover.png", type: "file", size: 456789, mime: "image/png", ext: "png", url: "http://...", download: "http://.../download/...", modified: 1708200000000 },
//     ...
//   ]
// }

URL Helpers

// Get direct file URL (inline viewing)
server.getFileURL('events/wedding/photo.png');
// => "http://192.168.1.10:8080/events/wedding/photo.png"

// Get download URL (forces download with Content-Disposition header)
server.getDownloadURL('events/wedding/photo.png');
// => "http://192.168.1.10:8080/download/events/wedding/photo.png"

// Get API URLs
server.getFilesAPIUrl();
// => "http://192.168.1.10:8080/api/files"

server.getDirAPIUrl('events/wedding');
// => "http://192.168.1.10:8080/api/dir/events/wedding"

Get WiFi IP Address

const ip = await StaticServer.getIPAddress();
console.log(ip); // "192.168.1.10"

React Native Example with Cleanup

import React, { useEffect, useRef } from 'react';
import StaticServer from 'react-native-local-server';
import * as FileSystem from 'expo-file-system';

function MyScreen() {
  const serverRef = useRef(null);

  useEffect(() => {
    const startServer = async () => {
      const rootDir = FileSystem.documentDirectory + 'my-files/';
      const server = new StaticServer(3000, rootDir);
      const url = await server.start();
      serverRef.current = server;
      console.log('Server at:', url);
    };

    startServer();

    return () => {
      // Cleanup on unmount
      if (serverRef.current) {
        serverRef.current.stop();
        serverRef.current = null;
      }
    };
  }, []);

  return <View />;
}

API Reference

new StaticServer(port, root, options?)

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | port | number | 8080 | Port to listen on | | root | string | '' | Absolute path to the directory to serve | | options.localOnly | boolean | false | Bind to 127.0.0.1 only |

Instance Methods

| Method | Returns | Description | |--------|---------|-------------| | start() | Promise<string> | Start server, returns URL | | stop() | Promise<void> | Stop server | | isRunning() | Promise<boolean> | Check if server is running | | getURL() | string \| null | Get server URL (sync) | | getFiles() | Promise<Object> | List all files recursively (JSON) | | getDir(path?) | Promise<Object> | List directory contents non-recursively (JSON) | | getFileURL(path) | string \| null | Get direct URL for a file | | getDownloadURL(path) | string \| null | Get forced-download URL for a file | | getFilesAPIUrl() | string \| null | Get /api/files endpoint URL | | getDirAPIUrl(path?) | string \| null | Get /api/dir endpoint URL |

Static Methods

| Method | Returns | Description | |--------|---------|-------------| | StaticServer.getIPAddress() | Promise<string> | Get device WiFi IP address |

HTTP Endpoints

When the server is running, these endpoints are available:

| Endpoint | Description | |----------|-------------| | GET / | Serve root directory (index.html or directory listing) | | GET /<path> | Serve file or directory at path | | GET /api/files | JSON array of all files (recursive) | | GET /api/dir | JSON listing of root directory contents | | GET /api/dir/<path> | JSON listing of subdirectory contents | | GET /download/<path> | Force download file with Content-Disposition: attachment |

Supported MIME Types

Images: png, jpg, jpeg, gif, webp, svg, ico, bmp, tiff, heic, heif Web: html, css, js, json, xml, txt, csv Video: mp4, mov, avi, webm Audio: mp3, wav, ogg, m4a Documents: pdf, zip Fonts: woff, woff2, ttf, otf, eot

Unrecognized extensions default to application/octet-stream.

Platform Details

| | iOS | Android | |---|---|---| | Socket implementation | BSD sockets + GCD dispatch_source | Java ServerSocket + ExecutorService | | File streaming | NSFileHandle (256KB chunks) | BufferedInputStream (256KB chunks) | | WiFi interface | en0 / en1 | wlan0 / eth0 | | Min version | iOS 13.0 | Android SDK 21 | | Permissions | None required | INTERNET, ACCESS_WIFI_STATE (auto-merged) |

License

ISC