Skip to main content

​
Package manager

Install the package from the npm registry: 
npm install @cloudflare/speedtest
Node.js >=12 is required when using the package in a Node.js-based build toolchain (e.g., bundling with Vite, webpack, or esbuild). At runtime the SDK targets browser environments — it relies on the performance global and the PerformanceResourceTiming API, which are not available in a plain Node.js process.

​
CDN usage

You can import the SDK directly in a browser <script type="module"> without a build step using the Skypack CDN: 
import SpeedTest from 'https://cdn.skypack.dev/@cloudflare/speedtest';

new SpeedTest().onFinish = results => console.log(results.getSummary());
This is the approach used in the browser-based quickstart example and requires no local installation.

​
ES module format

The package is published as an ES module. Its package.json includes "type": "module" and the main entry point is: 
./dist/speedtest.js
Import the default export in your application: 
import SpeedTest from '@cloudflare/speedtest';
Because the package is an ES module, you cannot use require('@cloudflare/speedtest') in CommonJS environments. Use a bundler that handles ES module interop, or use a dynamic import() call.

​
TypeScript support

TypeScript type definitions are bundled with the package at dist/speedtest.d.ts. No separate @types/ package is needed. The definitions cover:
  • The SpeedTest class and its constructor ConfigOptions
  • All event handler signatures (onRunningChange, onResultsChange, onFinish, onError, onPhaseChange)
  • The Results class and every result method
  • The MeasurementConfig union type for the measurements array
  • The BandwidthPoint interface returned by getDownloadBandwidthPoints() and getUploadBandwidthPoints()
Example with type annotations: 
import SpeedTest, { ConfigOptions, Results } from '@cloudflare/speedtest';

const config: ConfigOptions = {
  autoStart: false,
  bandwidthPercentile: 0.9,
  latencyPercentile: 0.5
};

const engine = new SpeedTest(config);

engine.onFinish = (results: Results) => {
  const summary = results.getSummary();
  console.log(summary.download, summary.latency);
};

engine.play();

​
Verify the installation

After installing, run the following to confirm the package resolves correctly: 
node --input-type=module --eval "import SpeedTest from '@cloudflare/speedtest'; console.log(typeof SpeedTest);"
You should see function printed to stdout.
If you see an error about performance not being defined, you are running the SDK in a Node.js context without a browser-compatible performance global. The SDK is designed to run in browser environments. When testing in Node.js, you must polyfill performance or run the code in a browser or browser-like environment such as jsdom.

Build docs developers (and LLMs) love

Get started for freeTalk to us