huytdps13400/react-native-ssl-manager / .agents/skills/nitro-fetch
nitro-fetch
VerifiedFast 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.0 KB |
| references/axios-adapter.md | markdown | 7.8 KB |
| references/migrate-from-rn-ws.md | markdown | 8.5 KB |
| references/network-inspector.md | markdown | 9.9 KB |
| references/perfetto-profiling.md | markdown | 10.1 KB |
| references/prefetching.md | markdown | 19.6 KB |
| references/text-decoder.md | markdown | 6.2 KB |
| references/using-websockets.md | markdown | 8.9 KB |
| references/websocket-prewarm.md | markdown | 8.5 KB |
references/using-websockets.md
View on GitHub---
id: using-websockets
title: Using NitroWebSocket (ws and wss)
scope: react-native-nitro-websockets
keywords: websocket, wss, tls, libwebsockets, mbedtls, headers, binary
---
# Using `NitroWebSocket`
## Mental model
`NitroWebSocket` is a browser-shaped WebSocket class backed by **libwebsockets + mbedTLS** under the hood. It looks and feels like the standard `WebSocket` you're used to, with three concrete differences that exist for good reasons:
| Difference | Why |
|---|---|
| Constructor takes a third `headers` argument | RN's built-in WebSocket can't send custom upgrade headers on iOS. This one can. |
| `readyState` is a string (`'OPEN'`, etc.) instead of a number | Easier to read, no constants to remember. |
| Binary frames come back as `e.binaryData: ArrayBuffer` (with `e.isBinary` flag) | No `binaryType` setter; binary and text are always distinguishable. |
For TLS, the package ships its own Mozilla CA bundle and validates against it via mbedTLS. That means `wss://` works the same on physical iOS devices, simulators, emulators, and old Android builds — you don't depend on the system trust store.
For migrating from React Native's built-in `WebSocket`, see the [migration skill](./migrate-from-rn-ws.md).
## Why use NitroWebSocket
- **Custom upgrade headers on every platform.** Auth tokens, tenant IDs, client metadata — all on the upgrade request, including on iOS where RN's built-in WebSocket doesn't support headers at all.
- **First-class binary frames.** No `Blob` round-trip, no `binaryType` toggle — binary and text are distinguished by `e.isBinary`.
- **Native UTF-8 decoding for text frames** via `react-native-nitro-text-decoder` — text payloads arrive as JS strings without you doing any decoding.
- **Bundled CA trust store.** Mozilla's `cacert.pem` is compiled in via mbedTLS, so `wss://` behaves identically on physical devices, simulators, and old Android builds.
- **Pre-warmable.** Pair with `prewarmOnAppStart` to have the connection already `OPEN` before React Native boots.
- **Inspector-aware.** When `NetworkInspector` is enabled, every `NitroWebSocket` automatically records its open / messages / close into the inspector log.
## Setup
Install three packages — the WebSocket class, the fetch package (the inspector lives there and `NitroWebSocket` autoregisters with it when present), and the text decoder (it's used internally to decode incoming text frames):
```bash
npm install \
react-native-nitro-websockets \
react-native-nitro-fetch \
react-native-nitro-text-decoder \
react-native-nitro-modules
cd ios && pod install
```
`react-native-nitro-modules` is the shared Nitro runtime; the other three are independent packages you'll use throughout the app. `react-native-nitro-fetch` and `react-native-nitro-text-decoder` are technically declared as peer deps of `react-native-nitro-websockets`, but installing them explicitly makes the dependency obvious in your `package.json` and prevents version drift on `bun` / `yarn` workspaces.
> **Why nitro-fetch even if you only use WebSockets?** `NitroWebSocket` does a `try { require('react-native-nitro-fetch').NetworkInspector } catch {}` at load time and silently no-ops if it's missing. Installing the fetch package gives you in-app WebSocket recording for free; skipping it just means you won't see WS entries in the inspector.
## API at a glance
```ts
import { NitroWebSocket } from 'react-native-nitro-websockets';
import type {
WebSocketMessageEvent,
WebSocketCloseEvent,
} from 'react-native-nitro-websockets';
class NitroWebSocket {
constructor(
url: string,
protocols?: string | string[],
headers?: Record<string, string>,
);
// State (all read-only)
readonly readyState: 'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED';
readonly url: string;
readonly protocol: string;
readonly bufferedAmount: number;
readonly extensions: string;
// Handlers — assignment, not addEventListener
onopen: (() => void) | null;
onmessage: ((e: WebSocketMessageEvent) => void) | null;
onclose: ((e: WebSocketCloseEvent) => void) | null;
onerror: ((error: string) => void) | null;
// Methods
send(data: string | ArrayBuffer): void;
close(code?: number, reason?: string): void;
}
type WebSocketMessageEvent = {
data: string; // decoded UTF-8 (empty when binary)
isBinary: boolean;
binaryData?: ArrayBuffer; // present iff isBinary
};
```
Source: [`packages/react-native-nitro-websockets/src/index.ts`](https://github.com/margelo/react-native-nitro-fetch/tree/main/packages/react-native-nitro-websockets/src/index.ts).
## Recipes
> **Do not swap `globalThis.WebSocket`.** Monkey-patching globals breaks devtools, hot reload, and third-party libraries that reach into the runtime assuming the spec shape. Always import `NitroWebSocket` explicitly at the call sites where you want the native implementation — this also keeps your grep history honest about where the nitro socket is used.
### `ws://` echo client
```ts
import { NitroWebSocket } from 'react-native-nitro-websockets';
const ws = new NitroWebSocket('ws://localhost:8080/echo');
ws.onopen = () => ws.send('hello');
ws.onmessage = (e) => console.log('text:', e.data);
ws.onclose = (e) => console.log('closed', e.code, e.reason);
ws.onerror = (err) => console.warn('ws error', err);
```
### `wss://` with auth headers
The constructor's third argument is the reason most teams reach for this package:
```ts
const ws = new NitroWebSocket(
'wss://stream.example.com/feed',
['v1.feed.proto'], // optional subprotocols
{
Authorization: `Bearer ${token}`,
'X-Tenant': 'acme',
},
);
```
The headers go on the upgrade request via libwebsockets' `LWS_CALLBACK_CLIENT_APPEND_HANDSHAKE_HEADER` hook.
### Binary frames in and out
```ts
ws.onmessage = (e) => {
if (e.isBinary && e.binaryData) {
const view = new Uint8Array(e.binaryData);
handleBinary(view);
} else {
handleText(e.data);
}
};
// Sending: ArrayBuffer → binary frame, string → text frame
ws.send('hello');
const buf = new Uint8Array([0x01, 0x02, 0x03, 0x04]).buffer;
ws.send(buf);
```
### Lifecycle in a React screen
`NitroWebSocket` instances aren't garbage-collected when a component unmounts. Always close in cleanup:
```tsx
function FeedScreen() {
useEffect(() => {
const ws = new NitroWebSocket('wss://stream.example.com/feed');
ws.onmessage = (e) => /* ... */;
return () => ws.close();
}, []);
return <View />;
}
```
For long-lived sockets that should outlive a single screen, hoist the instance to a module variable or context.
## Differences from `WebSocket` (cheat sheet)
| | Standard `WebSocket` | `NitroWebSocket` |
|---|---|---|
| `readyState` | numeric (0–3) | string (`'OPEN'` etc.) |
| Custom upgrade headers | not supported on iOS | ✅ third constructor arg |
| Binary frames | `binaryType` toggle | `e.isBinary` + `e.binaryData` |
| `addEventListener` | yes | **no** — use property assignment |
| `Blob` payloads | yes | no — pass an `ArrayBuffer` |
| TLS roots | OS trust store | bundled Mozilla CA via mbedTLS |
| Pre-warming | n/a | yes ([prewarm skill](./websocket-prewarm.md)) |
For migrating an existing app, see [`migrate-from-rn-ws.md`](./migrate-from-rn-ws.md).
## Gotchas
- **Numeric `readyState` checks.** `if (ws.readyState === 1)` is always false here. Use `'OPEN'`.
- **`addEventListener` not implemented.** Property assignment only.
- **Reading `e.data` for binary frames.** It's the empty string. Always check `e.isBinary` first.
- **Sending a `Blob` or `Buffer`.** Throws. Convert: `send(uint8.buffer.slice(uint8.byteOffset, uint8.byteOffset + uint8.byteLength))`.
- **Forgetting `ws.close()` in `useEffect` cleanup.** The native socket stays alive, the JS object stays referenced, and you slowly leak.
- **Multiple sockets to the same URL.** Allowed. But pre-warming only adopts the *first* one — subsequent constructors open fresh connections.
## Pointers
- Source: [`packages/react-native-nitro-websockets/src/index.ts`](https://github.com/margelo/react-native-nitro-fetch/tree/main/packages/react-native-nitro-websockets/src/index.ts)
- C++ side: [`packages/react-native-nitro-websockets/cpp/HybridWebSocket.cpp`](https://github.com/margelo/react-native-nitro-fetch/tree/main/packages/react-native-nitro-websockets/cpp/HybridWebSocket.cpp)
- Bundled CA: [`packages/react-native-nitro-websockets/android/src/main/cpp/cacert.pem`](https://github.com/margelo/react-native-nitro-fetch/tree/main/packages/react-native-nitro-websockets/android/src/main/cpp/cacert.pem)
- Working example: [`example/src/screens/WebSocketScreen.tsx`](https://github.com/margelo/react-native-nitro-fetch/tree/main/example/src/screens/WebSocketScreen.tsx)
- Long-form docs: [`docs-website/docs/websockets.md`](https://github.com/margelo/react-native-nitro-fetch/tree/main/docs-website/docs/websockets.md)
- Related: [`websocket-prewarm.md`](./websocket-prewarm.md), [`migrate-from-rn-ws.md`](./migrate-from-rn-ws.md), [`network-inspector.md`](./network-inspector.md)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |