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/text-decoder.md
View on GitHub---
id: text-decoder
title: Native UTF-8 decoding with react-native-nitro-text-decoder
scope: react-native-nitro-text-decoder
keywords: textdecoder, utf-8, jsi, nitro, binary, decoding
---
# `react-native-nitro-text-decoder`
## Mental model
A small package with one job: provide a JSI-backed `TextDecoder` for React Native that's **roughly 50× faster than the built-in JS shim** expo ships with. The decode work happens in C++ on the JS thread with no bridge round-trip.
It's deliberately a thin wrapper:
- One class — `TextDecoder`.
- UTF-8 only (no `'utf-16le'`, no `'iso-8859-1'`, etc.).
- No `TextEncoder` (use `Buffer.from(str, 'utf8')` if you need encoding).
- No `install()` polyfill. If you want a global, see the recipe below.
This package is also a peer dep of `react-native-nitro-websockets`, which uses it internally to decode incoming text frames. So if you already have nitro WebSockets installed, the package is on your device — just import the class.
## Why use this
- **~50× faster than the JS shim.** On large WebSocket frames or `arrayBuffer()` bodies the difference shows up in profiles immediately — the JS shim allocates and walks UTF-8 byte by byte; this one calls into C++.
- **JSI-backed, no bridge.** The decode call is a direct JSI invocation; there's no async hop or serialisation cost.
- **Available everywhere.** The shim Hermes ships is incomplete on older RN versions. This is the same class on every device, every OS, every engine.
- **Reused across packages.** `react-native-nitro-websockets` already uses this internally. Installing it for your own decode work doesn't add new native code beyond what you're already shipping.
## Setup
```bash
# pick your manager
npm install react-native-nitro-text-decoder react-native-nitro-modules
yarn add react-native-nitro-text-decoder react-native-nitro-modules
bun add react-native-nitro-text-decoder react-native-nitro-modules
cd ios && pod install
```
`react-native-nitro-modules` is a peer dep — install it once for the whole app.
## API
```ts
import { TextDecoder } from 'react-native-nitro-text-decoder';
class TextDecoder {
constructor(label?: string, options?: { fatal?: boolean; ignoreBOM?: boolean });
readonly encoding: string;
readonly fatal: boolean;
readonly ignoreBOM: boolean;
decode(
input?: ArrayBuffer | ArrayBufferView,
options?: { stream?: boolean }
): string;
}
```
What's actually supported:
| Knob | Behaviour |
|---|---|
| `label` | `'utf-8'` (default) and aliases (`'utf8'`, `'unicode-1-1-utf-8'`). Anything else throws. |
| `fatal: true` | Invalid UTF-8 throws instead of yielding U+FFFD. |
| `ignoreBOM: true` | A leading byte-order mark is dropped instead of being included. |
| `decode(buf, { stream: true })` | Holds incomplete code points until the next call so you can chunk binary input. |
Source: [`packages/react-native-nitro-text-decoder/src/TextDecoder.ts`](https://github.com/margelo/react-native-nitro-fetch/tree/main/packages/react-native-nitro-text-decoder/src/TextDecoder.ts).
## Recipes
### Decode a binary fetch body
```ts
import { fetch } from 'react-native-nitro-fetch';
import { TextDecoder } from 'react-native-nitro-text-decoder';
const decoder = new TextDecoder('utf-8'); // create once, reuse
const res = await fetch('https://api.example.com/snapshot.bin');
const buf = await res.arrayBuffer();
const data = JSON.parse(decoder.decode(buf));
```
### Decode WebSocket binary frames
For *text* frames `react-native-nitro-websockets` already decodes for you (`e.data` is a string). You only need a decoder for **binary** frames:
```ts
import { NitroWebSocket } from 'react-native-nitro-websockets';
import { TextDecoder } from 'react-native-nitro-text-decoder';
const decoder = new TextDecoder('utf-8', { fatal: false, ignoreBOM: true });
const ws = new NitroWebSocket('wss://stream.example.com/ticks');
ws.onmessage = (e) => {
if (e.isBinary && e.binaryData) {
const text = decoder.decode(e.binaryData);
handleTick(JSON.parse(text));
} else {
handleTick(JSON.parse(e.data));
}
};
```
### Streaming decode across chunks
Pass `{ stream: true }` for every chunk except the final one. The trailing call (with no argument) flushes any incomplete sequence:
```ts
const decoder = new TextDecoder('utf-8');
let acc = '';
for await (const chunk of someAsyncByteIterator) {
acc += decoder.decode(chunk, { stream: true });
}
acc += decoder.decode(); // flush
```
### Libraries that use `globalThis.TextDecoder`
Some libraries (`protobufjs`, `msgpack-lite`, certain WASM glue) reach for `globalThis.TextDecoder`. **Don't** swap it with the nitro implementation — `nitro-text-decoder` is UTF-8 only, so a library that constructs `new TextDecoder('utf-16le')` will throw under the polyfill, and monkey-patching a web-standard global hides the failure until production.
Prefer one of:
- Use the library's native output and decode the bytes yourself with the explicit nitro decoder import.
- Pass a decoder to the library if it accepts one as an option.
- Leave the library on Hermes' built-in `TextDecoder` — it's slower, but only for that one library.
## Gotchas
- **Subarrays of larger buffers.** `decoder.decode(uint8.subarray(0, 16))` works, but if you pass the *backing* `ArrayBuffer` directly you'll decode from offset 0 of the parent. Pass the typed-array view, not its `.buffer`.
- **Forgetting `pod install`.** The iOS build will fail to find the module. Always run `pod install` after adding the package.
- **Allocating a decoder per call.** The constructor goes through JSI, the decode call is the cheap one. Hold a module-level instance and reuse it.
- **Reaching for `TextEncoder`.** Not exported here. Use `Buffer.from(str, 'utf8')` from `buffer`, or another package.
- **Non-UTF-8 encodings.** Don't exist in this package. If you need them, decode manually or pull in `text-encoding`.
## Pointers
- Source: [`packages/react-native-nitro-text-decoder/src`](https://github.com/margelo/react-native-nitro-fetch/tree/main/packages/react-native-nitro-text-decoder/src)
- Used internally by: [`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) (look for `utf8Decoder`)
- Pairs with: [`using-websockets.md`](./using-websockets.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 |