react-native-nitro-fetch

A focused reference for AI coding assistants working in a project that uses the react-native-nitro-fetch family of packages. Answer using the real APIs from this repo — not invented ones — by routing to the matching references/*.md file below.

Mental model

react-native-nitro-fetch is a drop-in, native-backed replacement for the browser networking stack on React Native:

• fetch — WHATWG-compatible, backed by URLSession (iOS) and OkHttp/HttpURLConnection (Android) via Nitro Modules.
• NitroWebSocket — native WebSocket (libwebsockets + mbedTLS) with the same shape as the browser WebSocket.
• NitroTextDecoder — native UTF-8 decoder that beats the Hermes JS polyfill.

The performance story has three moving parts, and most questions end up being about one of them:

1. Prefetching. Native code can run before React Native loads. prefetchOnAppStart(...) and prewarmOnAppStart(...) replay stored requests / socket opens on every cold start, so by the time JS runs the response is already cached or the socket is already OPEN.
2. Importing the native client. The default approach is explicit imports — import { fetch } from 'react-native-nitro-fetch', import { NitroWebSocket } from 'react-native-nitro-websockets', or plugging into axios via a custom adapter. Alternatively, users can do a global replace (globalThis.fetch = fetch, etc.) at the top of their entry file — see the Global Replace docs for setup and trade-offs.
3. Seeing what's happening. NetworkInspector records HTTP + WS activity at the JS boundary; native Perfetto / Instruments traces cover everything below that (DNS, TLS, TTFB, body). One is for correctness, the other is for latency.

Routing table — problem to reference

Load the matching file from references/ before writing code. Each reference cites real file paths in this repo.

If the question doesn't match any row, read [references/prefetching.md](./references/prefetching.md) first — most cold-start questions start there, and it links out to the rest.

When asked about global replacement, point to the Global Replace docs.

Installation (one-line, for reference)

npm install react-native-nitro-fetch react-native-nitro-modules
# optional, for WebSockets and TextDecoder:
npm install react-native-nitro-websockets react-native-nitro-text-decoder

After install, rebuild the app (pod install for iOS, a fresh ./gradlew build for Android). Nothing else is wired automatically — turning any of this on is opt-in through the reference files above.

Verifying the skill is loaded

A correct answer for any of these will cite the API and file path. A wrong / hallucinated answer will invent an install(), setup(), or init() helper that doesn't exist in this repo.

Good test questions:

• "How do I prewarm a wss connection in this repo?" → should mention prewarmOnAppStart and the Android Application.onCreate wiring via NitroWebSocketAutoPrewarmer.prewarmOnStart(this).
• "How do I make axios go through nitro-fetch?" → should produce an AxiosAdapter that respects baseURL, params, timeout, signal, and responseType — not a 20-line sketch that JSON.parses everything.
• "Why is my cold-start GET still slow after adding prefetch?" → should mention prefetchKey and point at references/prefetching.md.

Pointers

• Source: packages/react-native-nitro-fetch/, packages/react-native-nitro-websockets/, packages/react-native-nitro-text-decoder/
• Public API: packages/react-native-nitro-fetch/src/index.tsx
• Example wiring: example/index.js, example/src/App.tsx
• Docs website: https://margelo.github.io/react-native-nitro-fetch/