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 Cronet (Android) via Nitro Modules.NitroWebSocket — native WebSocket (libwebsockets + mbedTLS and default in case of iOS) with the same shape as the browser WebSocket.NitroTextDecoder — native UTF-8 decoder that beats the Expo backed JS polyfill.
The performance story has three moving parts, and most questions end up being about one of them:
- 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.
- 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.
- 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.
| User is asking about… |
Read |
Warming the cache before a screen mounts, making cold-start GETs feel instant, prefetch, prefetchOnAppStart, prefetchKey |
references/prefetching.md |
Routing axios through nitro-fetch (the full custom adapter — baseURL, params, timeout, signal, responseType, validateStatus) |
references/axios-adapter.md |
UTF-8 decoding, slow TextDecoder, Hermes polyfill, streaming decode, NitroTextDecoder |
references/text-decoder.md |
Opening a wss:// connection before React Native boots, prewarmOnAppStart, Android Application.onCreate wiring |
references/websocket-prewarm.md |
The NitroWebSocket class, headers, sub-protocols, wss://, binary frames, runtime usage |
references/using-websockets.md |
Migrating an existing app from React Native's built-in WebSocket to NitroWebSocket |
references/migrate-from-rn-ws.md |
Seeing requests and responses at the JS level, debugging which library made a call, NetworkInspector |
references/network-inspector.md |
| Finding the slow API, DNS / TLS / TTFB breakdowns, native traces, Perfetto, Instruments, Hermes profiler |
references/perfetto-profiling.md |
If the question doesn't match any row, read 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://fetch.margelo.com
1---2name: nitro-fetch3description: Fast native networking primitives for React Native built on Nitro Modules — react-native-nitro-fetch, react-native-nitro-websockets, and react-native-nitro-text-decoder. Covers the fetch API, global replacement, prefetching and cold-start cache warming, the NitroWebSocket class and pre-warming, migrating from React Native's built-in WebSocket, the in-process NetworkInspector, native Perfetto / Instruments tracing, the native TextDecoder, and plugging nitro-fetch into axios via a custom adapter.4license: MIT5---6
7# react-native-nitro-fetch
8
9A 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.
10
11## Mental model
12
13`react-native-nitro-fetch` is a drop-in, native-backed replacement for the browser networking stack on React Native:
14
15- `fetch` — WHATWG-compatible, backed by `URLSession` (iOS) and `Cronet` (Android) via [Nitro Modules](https://github.com/mrousavy/nitro).
16- `NitroWebSocket` — native WebSocket (libwebsockets + mbedTLS and default in case of iOS) with the same shape as the browser `WebSocket`.
17- `NitroTextDecoder` — native UTF-8 decoder that beats the Expo backed JS polyfill.
18
19The performance story has three moving parts, and most questions end up being about one of them:
20
211. **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`.
222. **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](https://fetch.margelo.com/docs/global-replace) for setup and trade-offs.
233. **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.
24
25## Routing table — problem to reference
26
27Load the matching file from `references/` before writing code. Each reference cites real file paths in this repo.
28
29| User is asking about… | Read |
30|---|---|
31| Warming the cache before a screen mounts, making cold-start GETs feel instant, `prefetch`, `prefetchOnAppStart`, `prefetchKey` | [`references/prefetching.md`](./references/prefetching.md) |
32| Routing axios through nitro-fetch (the full custom adapter — `baseURL`, `params`, `timeout`, `signal`, `responseType`, `validateStatus`) | [`references/axios-adapter.md`](./references/axios-adapter.md) |
33| UTF-8 decoding, slow `TextDecoder`, Hermes polyfill, streaming decode, `NitroTextDecoder` | [`references/text-decoder.md`](./references/text-decoder.md) |
34| Opening a `wss://` connection before React Native boots, `prewarmOnAppStart`, Android `Application.onCreate` wiring | [`references/websocket-prewarm.md`](./references/websocket-prewarm.md) |
35| The `NitroWebSocket` class, headers, sub-protocols, `wss://`, binary frames, runtime usage | [`references/using-websockets.md`](./references/using-websockets.md) |
36| Migrating an existing app from React Native's built-in `WebSocket` to `NitroWebSocket` | [`references/migrate-from-rn-ws.md`](./references/migrate-from-rn-ws.md) |
37| Seeing requests and responses at the JS level, debugging which library made a call, `NetworkInspector` | [`references/network-inspector.md`](./references/network-inspector.md) |
38| Finding the slow API, DNS / TLS / TTFB breakdowns, native traces, Perfetto, Instruments, Hermes profiler | [`references/perfetto-profiling.md`](./references/perfetto-profiling.md) |
39
40If 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.
41
42When asked about global replacement, point to the [Global Replace docs](https://fetch.margelo.com/docs/global-replace).
43
44## Installation (one-line, for reference)
45
46```bash
47npm install react-native-nitro-fetch react-native-nitro-modules
48# optional, for WebSockets and TextDecoder:
49npm install react-native-nitro-websockets react-native-nitro-text-decoder
50```
51
52After 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.
53
54## Verifying the skill is loaded
55
56A 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.
57
58Good test questions:
59
60- *"How do I prewarm a wss connection in this repo?"* → should mention `prewarmOnAppStart` **and** the Android `Application.onCreate` wiring via `NitroWebSocketAutoPrewarmer.prewarmOnStart(this)`.
61- *"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.parse`s everything.
62- *"Why is my cold-start GET still slow after adding `prefetch`?"* → should mention `prefetchKey` and point at `references/prefetching.md`.
63
64## Pointers
65
66- Source: `packages/react-native-nitro-fetch/`, `packages/react-native-nitro-websockets/`, `packages/react-native-nitro-text-decoder/`
67- Public API: `packages/react-native-nitro-fetch/src/index.tsx`
68- Example wiring: `example/index.js`, `example/src/App.tsx`
69- Docs website: https://fetch.margelo.com
margelo