How JSON.parse materializes entire documents in JavaScript, and how react-native-fast-json uses native simdjson + lazy JsonView access to change the cost model in React Native.

react-native-fast-json is an open-source React Native library that wraps simdjson in C++ and exposes a lazy JsonView through Nitro Modules.

Most teams treat JSON parsing as “cheap” because API responses are small. The mental model is:

bytes on wire → JSON.parse → plain objects in JS → app logic

That model breaks when the payload is hundreds of megabytes. The dominant cost is not “JSON syntax is slow” in the abstract, it is allocating and wiring up a full value tree in the JavaScript heap.

What JSON.parse actually does in React Native

When you call JSON.parse (or await response.json()), the engine:

1. Holds the UTF-16/UTF-8 string (or an internal representation of the body)
2. Walks the entire document
3. For every object, array, number, boolean, and string, creates JavaScript values with engine overhead (hidden classes, property storage, array backing stores, interned strings, etc.)

For a ~250 MB file, outcomes depend heavily on platform and available RAM:

On the data_250mb.json fixture in our tests: iOS could complete JSON.parse but only with extreme CPU and memory spikes; Android always crashed before parse finished, making JSON.parse impossible for that payload on Android, while native parseFile worked on both platforms.

Benchmark fixture (source)

Measurements in this repo use the public ~250 MB JSON from antonmedv/json-examples:

The example app downloads that URL, caches it on disk, then calls parseFile on the local path.

Measured results (parseFile, release builds, physical devices)

JSON.parse / response.json() on the same fixture:

The second row is not “free memory.” The file still occupies roughly file size + simdjson padding in native memory. The win is avoiding a second full copy as a giant JS object graph until you explicitly materialize pieces.

Why “read file as string, then JSON.parse” can be worse at peak

A common variant:

const text = await readFile(path, 'utf8');
const data = JSON.parse(text);

At peak you may briefly hold:

• The entire file as one JS string
• The entire parsed tree
• Parser scratch allocations

response.json() can sometimes avoid exposing one giant application-level string, but the end state is still the same: a full tree in JS. For large files, peak heap is the killer.

The technique: how react-native-fast-json does it

react-native-fast-json is what makes the native lazy model practical in React Native. Instead of returning a plain object from JSON.parse, it shifts work across a different boundary:

file bytes → native buffer (simdjson) → JsonView handle → read paths on demand

1. Native buffer (simdjson)

parseFile loads the file into a padded native buffer (simdjson::padded_string::load). Parsing runs in C++ with simdjson (SIMD-accelerated, widely used for large JSON).

The document’s canonical bytes live in native memory, not as nested JS objects.

2. Lazy JsonView (Nitro hybrid object)

The root returned to JavaScript is a JsonView, a Nitro hybrid object backed by C++. Calling:

• getValue('metadata')
• atPath('$.a.b.c')
• asString() on a scalar

…does targeted native work and only crosses the bridge with small results (another JsonView handle or a primitive), not the whole document.

3. Materialization is explicit and expensive

When you call:

• asObject(), subtree becomes a JS-friendly map/array structure
• rawJson(), subtree becomes a JS string

…you have chosen to pay the JS heap cost for that slice. On a 250 MB document, calling these on the root is equivalent to opting back into the problem you avoided.

Architecture

HybridFastJson (cpp/HybridFastJson.cpp):

• parseFile(path), load file, construct HybridJsonView, cache by path string
• parseString(str), copy string into native view (not path-cached)
• release(path), erase cache entry for that path

HybridJsonView, navigation, path helpers, scalar coercion, optional materialization.

Until release(path), a cached parseFile keeps the full native buffer alive even if JS drops its JsonView reference, plan releases when the flow ends.

What you still pay for (honest accounting)

There is no zero memory overhead. The claim that holds up is: near-zero additional JS heap for the full document while you navigate lazily.

Why milliseconds (or low hundreds of ms) are plausible for hundreds of MB

simdjson is designed for throughput on large valid JSON. On the data_250mb.json fixture, parseFile after the file is on disk landed at ~100 ms on iOS and ~500 ms on Android in our release builds, with stable CPU and memory. By contrast, JSON.parse on iOS took many seconds with extreme spikes; on Android it always crashed, so native parse was the only viable option there.

Caveats when you reproduce benchmarks:

• Fixture, use the same public file or disclose yours
• Cold vs warm storage (first read after download vs re-parse)
• Platform, Android was ~5× slower than iOS in our tests; do not assume one number for all devices
• Device tier and storage speed
• JSON shape (depth, string density) affects constant factors
• Debug vs release native builds, ship measurements on release binaries

Comparison table (same fixture, measured + observed)

Wildcards and paths

• atPath('$.a.b.c'), simple dotted segments, no [index] in the path string.
• atPathWithWildcard('$.items[*].id'), dynamic segments; returns string[] | null for matched scalar strings.

For very large documents, prefer narrow paths over scanning wildcards across the whole tree unless you have measured the cost.

When native lazy parsing is the wrong tool

Not a common use case, prefer better alternatives

Shipping ~250 MB JSON to a phone is a smell, not a pattern. We benchmark it because it stress-tests the parser and matches real legacy pain, not because every app should do it.

Try these first (usually cheaper than optimizing parse):

1. Don’t send the file, paginate, stream, or return only fields the UI needs.
2. Don’t use JSON on the wire, schema-driven binary formats decode faster and smaller.
3. Don’t keep one blob, SQLite (or similar) with indexes for the queries you actually run.
4. Don’t parse on the critical path, generate summaries or shards on the server; sync deltas.

Native lazy parsing is a mitigation when you are locked into large JSON. It is not a substitute for a sane data contract.

When this library still does not help enough

• Small payloads, JSON.parse is simpler and fast enough.
• You need the entire document in JS anyway, you will materialize everything eventually; measure whether native parse + bulk asObject() is still a win.
• Heavy in-place mutation of arbitrary subtrees in JS, work on plain objects.
• You cannot hold file-sized native RAM (low-RAM devices + multiple huge files), budget and serialize access; even native buffers are ~file size.

Benchmark methodology

import { fastJson } from 'react-native-fast-json';

const root = await fastJson.parseFile('/path/to/large.json');
const version = root?.getValue('metadata')?.getValue('version')?.asString();
fastJson.release('/path/to/large.json');

1. Fixture, data_250mb.json from antonmedv/json-examples, via https://github.com/antonmedv/json-examples/raw/refs/heads/master/data_250mb.json
2. RN Version 0.85.0, New Architecture.
3. Device, physical iOS and Android (document model, OS, RN version, Hermes on/off).
4. Build, release native binary.
5. Scenarios
   • A: response.json() or JSON.parse after full string in memory
   • B: download/cache to disk → parseFile(localPath) → read N fields → release(path)
6. Metrics, wall time to root JsonView, JS heap snapshot, CPU/memory stability in Instruments / Android Studio.
7. Our results, parseFile: iOS ~100 ms, Android ~500 ms, CPU/memory stable. JSON.parse: iOS many seconds with extreme spikes; Android always crashed on this fixture.

The example app implements download + parseFile + timing UI, use it as a starting point, not as universal truth.

Summary

Try react-native-fast-json

yarn add react-native-fast-json react-native-nitro-modules

Install pods, rebuild, then use fastJson.parseFile for large files on disk. Peer dependency: react-native-nitro-modules.