nitro-fetch

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

这是为使用

react-native-nitro-fetch

系列包的AI代码助手提供的专属参考文档。请通过下方匹配的

references/*.md

文件，使用本仓库中的真实API进行解答——请勿编造不存在的API。

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:

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.

react-native-nitro-fetch

是React Native浏览器网络栈的即插即用型原生替代方案：

```
fetch
```
— 兼容WHATWG标准，通过Nitro Modules基于iOS的
```
URLSession
```
和Android的
```
OkHttp
```
/
```
HttpURLConnection
```
实现。
```
NitroWebSocket
```
— 原生WebSocket（基于libwebsockets + mbedTLS），接口与浏览器
```
WebSocket
```
一致。
```
NitroTextDecoder
```
— 原生UTF-8解码器，性能优于Hermes JS polyfill。

其性能优化主要体现在三个方面，大多数问题也围绕这三点展开：

预取（Prefetching）：原生代码可在React Native加载前运行。
```
prefetchOnAppStart(...)
```
和
```
prewarmOnAppStart(...)
```
会在每次冷启动时重放已存储的请求/套接字打开操作，这样当JS代码运行时，响应已缓存完毕或套接字已处于
```
OPEN
```
状态。
导入原生客户端：默认方式是显式导入——
```
import { fetch } from 'react-native-nitro-fetch'
```
、
```
import { NitroWebSocket } from 'react-native-nitro-websockets'
```
，或通过自定义适配器接入axios。此外，用户也可在入口文件顶部进行全局替换（
```
globalThis.fetch = fetch
```
等）——详见全局替换文档了解设置方法和利弊。
监控网络活动：
```
NetworkInspector
```
在JS层记录HTTP + WS活动；原生Perfetto/Instruments追踪则覆盖JS层以下的所有环节（DNS、TLS、TTFB、请求体）。前者用于验证正确性，后者用于排查延迟问题。

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.

编写代码前，请先加载

references/

目录下对应的文件。每个参考文档都会引用本仓库中的真实文件路径。

用户询问的内容…	参考文档
在页面挂载前预热缓存、让冷启动GET请求瞬间响应、 `prefetch` 、 `prefetchOnAppStart` 、 `prefetchKey`	`references/prefetching.md`
将axios通过nitro-fetch路由（完整自定义适配器——支持 `baseURL` 、 `params` 、 `timeout` 、 `signal` 、 `responseType` 、 `validateStatus` ）	`references/axios-adapter.md`
UTF-8解码、缓慢的 `TextDecoder` 、Hermes polyfill、流式解码、 `NitroTextDecoder`	`references/text-decoder.md`
在React Native启动前打开 `wss://` 连接、 `prewarmOnAppStart` 、Android `Application.onCreate` 配置	`references/websocket-prewarm.md`
`NitroWebSocket` 类、请求头、子协议、 `wss://` 、二进制帧、运行时使用方法	`references/using-websockets.md`
将现有应用从React Native内置 `WebSocket` 迁移到 `NitroWebSocket`	`references/migrate-from-rn-ws.md`
在JS层查看请求与响应、调试哪个库发起了调用、 `NetworkInspector`	`references/network-inspector.md`
定位缓慢的API、DNS/TLS/TTFB耗时分析、原生追踪、Perfetto、Instruments、Hermes性能分析器	`references/perfetto-profiling.md`

如果问题与上述任何一行都不匹配，请先阅读

references/prefetching.md

——大多数冷启动问题都从这里开始，并且该文档会链接到其他相关内容。

当被问及全局替换时，请指向全局替换文档。

Installation (one-line, for reference)

安装（一行命令，供参考）

bash

npm install react-native-nitro-fetch react-native-nitro-modules

bash

npm install react-native-nitro-fetch react-native-nitro-modules

optional, for WebSockets and TextDecoder:

可选，如需WebSocket和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.

npm install react-native-nitro-websockets react-native-nitro-text-decoder


安装完成后，重新构建应用（iOS执行`pod install`，Android执行全新的`./gradlew`构建）。所有功能不会自动启用——需通过上述参考文档手动开启。

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.parse
```
s everything.
"Why is my cold-start GET still slow after adding
prefetch
?" → should mention
```
prefetchKey
```
and point at
```
references/prefetching.md
```
.

正确的回答会引用API和文件路径。错误/编造的回答会虚构本仓库中不存在的

install()

、

setup()

或

init()

辅助函数。

测试示例问题：

“如何在本仓库中预热wss连接？” → 应提及
```
prewarmOnAppStart
```
以及 Android端通过
```
NitroWebSocketAutoPrewarmer.prewarmOnStart(this)
```
在
```
Application.onCreate
```
中配置的方法。
“如何让axios使用nitro-fetch？” → 应生成一个支持
```
baseURL
```
、
```
params
```
、
```
timeout
```
、
```
signal
```
和
```
responseType
```
的
```
AxiosAdapter
```
——而非仅20行左右的
```
JSON.parse
```
代码示例。
“为什么添加
prefetch
后我的冷启动GET请求仍然缓慢？” → 应提及
```
prefetchKey
```
并指向
```
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/

源码：

packages/react-native-nitro-fetch/

、

packages/react-native-nitro-websockets/

、

packages/react-native-nitro-text-decoder/

公开API：

packages/react-native-nitro-fetch/src/index.tsx

示例配置：
```
example/index.js
```
、
```
example/src/App.tsx
```
文档网站：https://margelo.github.io/react-native-nitro-fetch/