Registry /
web-framework / react-native-static-server
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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StaticServer
✓ import StaticServer from 'react-native-static-server';
✗ import { StaticServer } from 'react-native-static-server';
StaticServer is a default export. Using named import will result in an undefined error.
RNFS
✓ import RNFS from 'react-native-fs';
✗ const RNFS = require('react-native-fs');
While react-native-fs is a separate dependency, it's almost always used alongside StaticServer for path management. Ensure it's installed: `npm install react-native-fs`.
StaticServer options object
✓ new StaticServer({ localOnly: true, keepAlive: true });
Options can be passed as a single object, or after port and path arguments. For example, `new StaticServer(8080, path, { localOnly: true });`
Demonstrates how to initialize and start a static HTTP server, write a simple HTML file to the document directory, and serve it. It includes options for local-only access and keeping the server alive in the background. Note: `react-native-fs` is required for this example.
import StaticServer from 'react-native-static-server';
import RNFS from 'react-native-fs';
import { Platform } from 'react-native';
const startStaticServer = async () => {
const serverPort = 8080;
// Create a directory for static files if it doesn't exist
const wwwPath = `${RNFS.DocumentDirectoryPath}/www`;
if (!(await RNFS.exists(wwwPath))) {
await RNFS.mkdir(wwwPath);
}
// Write a simple index.html file
const indexPath = `${wwwPath}/index.html`;
await RNFS.writeFile(indexPath, '<h1>Hello from Static Server!</h1><p>Served from: ' + wwwPath + '</p>', 'utf8');
console.log(`Wrote index.html to ${indexPath}`);
// Instantiate the server
const server = new StaticServer(serverPort, wwwPath, {
localOnly: true,
keepAlive: true
});
try {
const url = await server.start();
console.log('Static server started at URL:', url);
console.log('Access it on your device at:', `${Platform.OS === 'ios' ? 'http://localhost' : 'http://127.0.0.1'}:${serverPort}/index.html`);
// In a real app, you might store the server instance or its URL
// to stop it later or open a WebView.
} catch (error) {
console.error('Failed to start static server:', error);
}
// To stop the server later:
// server.stop().then(() => console.log('Server stopped'));
};
startStaticServer();
Debug
Known issues
breakingReact Native version 0.60 and above utilize autolinking. If upgrading from an older React Native version, the manual linking step `react-native link react-native-static-server` is no longer needed and should be removed. Ensure `pod install` is run in the `ios` directory after adding the package.fixFor React Native >= 0.60, remove manual linking. Always run `cd ios && pod install` after adding the package.
affects: >=0.60.0 of React Native
gotchaWhen serving from a custom folder on iOS (e.g., `MainBundlePath`), the folder containing static files *must* be explicitly added to Xcode as a 'folder reference' (blue folder icon, not yellow group). Failure to do so will prevent the files from being bundled with the app and the server will not find them.fixIn Xcode: Project Navigator -> Right click project folder -> 'Add Files to "<project>"' -> Select static folder -> Crucially, select 'Create folder references' (blue folder icon). Ensure 'Copy items if needed' is unchecked if you want to reference existing files.
affects: >=0.1.0
gotchaPassing `0` as the port number will assign a random available port. However, if `keepAlive` is not set to `true`, the server will re-assign a *new random port* every time the app unpauses from the background, making the URL unpredictable.fixIf using port `0` and requiring a consistent URL, always set the `keepAlive: true` option in the server configuration. Otherwise, retrieve the URL after each `server.start()` call.
affects: >=0.1.0
Errors
Common errors & fixes
Failed to start static server: Error: Directory not found
The specified path for serving files (e.g., `wwwPath`) does not exist on the device, or the app lacks permissions to access it.
fixEnsure the directory exists before starting the server. Use `react-native-fs` methods like `RNFS.mkdir()` to create the directory if it doesn't. For custom iOS paths, verify Xcode folder references as per warnings.
StaticServer is not a constructor (or similar 'undefined' error when creating server)
Incorrect import syntax for `StaticServer`.
fixEnsure `StaticServer` is imported as a default export: `import StaticServer from 'react-native-static-server';` instead of `import { StaticServer } from 'react-native-static-server';`. Invariant Violation: 'RCTStaticServer' module is not a registered callable module.
The native module for react-native-static-server was not correctly linked or initialized.
fixFor React Native < 0.60, ensure `react-native link react-native-static-server` was run. For RN >= 0.60, ensure `cd ios && pod install` was executed after `npm install` and restart your bundler and app. Clean build caches if necessary.
Audit
Dependencies
reactrequiredPeer dependency for React Native environment.
react-nativerequiredCore peer dependency for React Native functionality.
react-native-fsoptionalCommonly used for accessing file system paths, as demonstrated in server configuration examples. Not a direct peer dependency, but practically essential for many use cases.