What is @cloudflare/speedtest?
@cloudflare/speedtest is a JavaScript module that measures the quality of a client’s Internet connection. It is the measurement engine that powers speed.cloudflare.com — Cloudflare’s public Internet speed test application.
The module performs test requests against the Cloudflare edge network and relies on the browser’s PerformanceResourceTiming API to extract precise timing results from each request. This means the SDK runs entirely in the browser — no native plugins or server-side components required.
Measurement results are collected by Cloudflare on completion for the purpose of calculating aggregated insights about Internet connection quality.
What it measures
@cloudflare/speedtest characterizes a network connection across several dimensions:
| Metric | Description |
|---|---|
| Download bandwidth | Transfer speed from the Cloudflare edge to the client, in bits per second (bps). Measured by downloading payloads of increasing sizes. |
| Upload bandwidth | Transfer speed from the client to the Cloudflare edge, in bps. Measured by posting payloads of increasing sizes. |
| Unloaded latency | Round-trip time-to-first-byte while the connection is idle. Reported at the configured percentile (default: median). |
| Loaded latency (download) | Round-trip latency measured in parallel while a download is in progress. Shows how latency degrades under load. |
| Loaded latency (upload) | Round-trip latency measured in parallel while an upload is in progress. |
| Jitter | Average deviation between consecutive latency measurements. High jitter indicates an unstable connection. |
| Packet loss | Ratio of UDP packets that do not complete a round trip via a WebRTC TURN server. |
How it works
Instantiation
You create a
SpeedTest instance, optionally passing configuration options. By default, autoStart: true means the engine begins immediately.Measurement sequence
The engine works through a configurable sequence of measurement steps. The default sequence begins with latency probes, then progressively larger download and upload payloads, and finally a packet loss test. It uses a ramp-up methodology — once requests reach a sufficient duration (
bandwidthFinishRequestDuration), larger payload steps in the same direction are skipped.Timing extraction
Each HTTP request is timed using the browser’s
PerformanceResourceTiming API. For bandwidth measurements, the engine divides the transferSize (in bits) by the request duration, subtracting any server processing time reported in the Server-Timing response header.Result aggregation
Individual measurements are reduced to single values using configurable percentiles (default: 90th percentile for bandwidth, 50th percentile for latency). Results are accessible at any point through the
results getter, and the onResultsChange event fires after each measurement completes.Key features
Zero-dependency measurement
Uses the standard
PerformanceResourceTiming browser API — no native plugins, WebAssembly, or server-side infrastructure needed beyond a modern browser.Loaded latency measurement
Measures latency concurrently with active download and upload transfers to show how your connection behaves under real-world load, not just at idle.
Configurable measurement sequence
The full measurement sequence — payload sizes, request counts, percentiles, and more — is customizable to suit your application’s requirements.
Live result streaming
Results are exposed incrementally as measurements complete via
onResultsChange. You can display live progress without waiting for the full test to finish.TypeScript support
Ships with bundled TypeScript type definitions (
dist/speedtest.d.ts), covering all config options, event handlers, and the full Results API.AIM scoring
Produces AIM scores that rate connection quality for common use cases: streaming, gaming, and real-time communication.
Browser requirements
The SDK depends on thePerformanceResourceTiming API, which is available in all modern browsers. The API must be able to observe cross-origin requests to speed.cloudflare.com — this works without any additional configuration in supported browsers.
The package targets environments where the global performance object is available. It is not intended for use in Node.js server-side contexts.
Data collection
When a test completes, a summary of the measurement results is sent to Cloudflare’s AIM API (aim.cloudflare.com/__log). Cloudflare uses this data to compute aggregated insights about Internet connection quality globally. No personally identifiable information is included in the measurement payload.