react-native-nitro-fetch

The react-native-nitro-fetch family provides a high-performance, native-backed networking stack for React Native. It serves as a drop-in replacement for standard browser APIs, leveraging Nitro Modules to move networking logic to native code (iOS URLSession and Android OkHttp/HttpURLConnection).

Core components include:

• fetch: A WHATWG-compatible fetch API.
• NitroWebSocket: A native WebSocket implementation (using libwebsockets + mbedTLS) that matches the browser WebSocket shape.
• NitroTextDecoder: A native UTF-8 decoder designed to outperform the Hermes JS polyfill.

The ecosystem focuses on three performance pillars: Prefetching (running requests/socket opens before JS loads), Native Client Integration (explicit imports or global replacement), and Observability (using NetworkInspector for JS-level debugging or native Perfetto/Instruments for low-level latency analysis).

WebSocket pre-warming is a side-channel optimization designed to eliminate the 500–1500ms delay caused by TCP, TLS, and HTTP upgrade handshakes during a React Native cold start.

The Mental Model:

1. Persist Intent: You call prewarmOnAppStart (e.g., after a user logs in) to save a URL and its headers to native storage.
2. Native Bootstrap: On the next app launch, before the JS engine starts, native code reads the queue and opens the connection on a background C++ thread. Any messages sent by the server during this boot phase are buffered.
3. JS Adoption: When your JS code eventually calls new NitroWebSocket(url, ...) with the exact same URL, the native layer hands over the already-open connection. The buffered messages are then replayed to your onmessage handler.

Important: Pre-warming is for the next launch. Calling pre-warm and then immediately constructing a socket in the same session provides no benefit.

import { NitroWebSocket } from 'react-native-nitro-websockets';

// The URL must match the pre-warmed URL exactly (including trailing slashes)
const ws = new NitroWebSocket(
  'wss://stream.example.com/feed', 
  ['v1.feed.proto'],
  { Authorization: `Bearer ${token}` }
);

When using prefetchOnAppStart or WebSocket prewarming (react-native-nitro-websockets), native code executes before your JavaScript bundle. If these requests require authentication, you must register a token refresh configuration.

On every cold start, the native layer will automatically call your specified refresh URL, map the response into the required headers or bodies, and merge them into your auto-prefetches or WebSocket prewarms. The configuration and resulting tokens are stored in platform-secure storage (Android Keystore/SharedPreferences and iOS Keychain).

import { registerTokenRefresh } from 'react-native-nitro-fetch';

registerTokenRefresh({
  target: 'fetch', // 'websocket' | 'fetch' | 'all'
  url: 'https://api.example.com/oauth/token',
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ grant_type: 'client_credentials' }),
  responseType: 'json',
  mappings: [
    {
      jsonPath: 'access_token',
      header: 'Authorization',
      valueTemplate: 'Bearer {{value}}',
    },
  ],
  onFailure: 'useStoredHeaders', // 'useStoredHeaders' (default) or 'skip'
});

In addition to http(s), fetch(...) supports several other URI schemes for reading local resources natively:

• data: URLs: Decoded in JS. If react-native-nitro-text-decoder is bundled, it uses that; otherwise, it falls back to a global TextDecoder. If neither is available, the body remains accessible via res.arrayBuffer() or res.bytes().
• file:// URLs and bare absolute paths: Read directly off disk natively.
• content:// URIs: Read via the ContentResolver on Android.

Important Limitations:

• blob: URLs are not supported and will reject with a TypeError because the React Native blob registry is not reachable from native.
• Local files return a 200 Response with a Content-Type automatically guessed from the file extension or the data: media type.

// data: URLs are decoded in JS
await fetch('data:text/plain;base64,SGVsbG8='); // -> "Hello"

// file:// URLs and bare absolute paths are read off disk natively
await fetch('file:///var/mobile/.../import.csv');
await fetch('/var/mobile/.../import.csv'); // scheme-less absolute path

// content:// URIs are read via the ContentResolver (Android)
await fetch('content://com.android.providers.../document/1234');

// Example: reading local files
import { fetch } from 'react-native-nitro-fetch';

const csv = await (await fetch(`file://${pickedFileUri}`)).text();
const config = await (await fetch(`${cacheDir}/config.json`)).json();