react-native-cf-speedtest

Measure internet connection quality (download/upload bandwidth, latency, jitter, AIM scores) in React Native apps against Cloudflare's edge network — a methodology-compatible port of @cloudflare/speedtest.

⚠️ Unofficial — not affiliated with or endorsed by Cloudflare. This is an independent, community-built library. It reuses the measurement methodology of the MIT-licensed @cloudflare/speedtest package (which powers speed.cloudflare.com), but Cloudflare, Inc. does not sponsor, support, or endorse this project. "Cloudflare" is a trademark of Cloudflare, Inc. See docs/adr/0006-naming-and-trademark.md.

Demo

Install

yarn add react-native-cf-speedtest
# or: npm install react-native-cf-speedtest

Requires React Native ≥ 0.76 (New Architecture / TurboModule). See Requirements.

npm: react-native-cf-speedtest · repo: Ky0-Nguyen/react-native-cf-speedtest

Run the demo (React Native CLI)

yarn
yarn example pod-install   # iOS — first time / after native changes
yarn example start         # Metro
# other terminal:
yarn example ios           # or: yarn example android

Details: example/README.md.

Why

@cloudflare/speedtest is browser-only. Pure-JS timing in React Native is inaccurate above roughly 200–300 Mbps (JS-thread jitter, GC, no PerformanceResourceTiming).

The fix: TypeScript orchestration (upstream methodology) + a thin native TurboModule for each timed transfer (URLSession / OkHttp). See docs/ARCHITECTURE.md.

Features

• Download / upload bandwidth (ramp-up, p90), unloaded + loaded latency, jitter
• AIM getScores() — streaming / gaming / video chatting (Bad → Great); packet loss optional (0 AIM points when not measured)
• SpeedTest API + useSpeedTest() hook, progress stream, maxTotalBytes, metered-connection guard
• Swift + Kotlin native transport (New Architecture)

UDP packet loss via TURN remains Phase 2.

Architecture overview

Business logic stays in TypeScript; native code only runs one timed transfer/probe and reports timing points.

• Native: streaming bodies, no full-payload buffers, monotonic clocks, cancellation — NATIVE-IMPLEMENTATION.md
• TypeScript: sequencing, percentiles, jitter, AIM — API-DESIGN.md

Quick start

import { SpeedTest } from 'react-native-cf-speedtest';

const test = new SpeedTest({
  autoStart: true,
  maxTotalBytes: 50_000_000,
});

test.onResultsChange = () => {
  console.log(test.results.getSummary());
};

test.onFinish = (results) => {
  console.log(results.getSummary());
  console.log(results.getScores());
};

Media assets

Files under media/ used in this README (also shipped in the npm package):

| File | Type | Purpose | |------|------|---------| | media/demo-speedtest.mp4 | Video (MP4) | Example-app demo video | | media/demo-speedtest.gif | Animated GIF | Same demo for inline README preview | | media/demo-poster.png | Image (PNG) | Poster / thumbnail for the demo video | | media/architecture-overview.png | Image (PNG) | Exported architecture diagram | | media/paypal-donate.jpg | Image (JPEG) | PayPal donate QR |

Documentation

Full docs (PRD, API, native, epics, ADRs): docs/README.md

Requirements

| Requirement | Value | |---|---| | React Native | >= 0.76 (New Architecture; TurboModule-only — ADR-0004) | | iOS | 15.1+ | | Android | minSdk 24 | | Expo Go | Not supported (native module) |

A full uncapped run can transfer hundreds of MB — use maxTotalBytes and the metered-connection warning on mobile.

Roadmap

| Phase | Goal | |---|---| | Phase 1 | Core library + example + AIM scoring + npm (shipped) | | Phase 2 | Packet loss (TURN), Expo config plugin, CI polish |

Details: docs/ROADMAP.md.

Contributing

See CONTRIBUTING.md.

Donate

If this library helps your project, support development via PayPal:

• Open: PayPal — Tuan Nguyen
• Or scan:

After install, run npm fund react-native-cf-speedtest to open the same link.

License

MIT © 2026 Tuan Nguyen.

Methodology ported from @cloudflare/speedtest (MIT). Unofficial — not affiliated with Cloudflare, Inc.