bundlephobia-api-client

TypeScript client for the Bundlephobia public API. Works in Node.js and the browser (isomorphic). Fully typed, zero runtime dependencies.

Installation

npm install bundlephobia-api-client

Quick start

import { BundlephobiaClient } from 'bundlephobia-api-client';

const client = new BundlephobiaClient();

// Bundle size for the latest version (await directly)
const size = await client.package('react');
console.log(size.gzip); // 2670

// Bundle size for a specific version
const size18 = await client.package('react').size('18.2.0');

// Size history across all versions
const history = await client.package('react').history();

// Similar / alternative packages
const similar = await client.package('react').similar();

API reference

Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | client.package(name) | — | Returns a chainable PackageResource | | client.package(name).size(version?, signal?) | GET /api/size?package={name}@{version} | Bundle size for a specific version (default: latest) | | client.package(name).history(signal?) | GET /api/package-history?package={name} | Size history across all published versions | | client.package(name).similar(signal?) | GET /api/similar-packages?package={name} | Similar/alternative packages with bundle sizes |

Bundle size

// Latest version — await the resource directly
const size = await client.package('react');

// Or call .size() explicitly
const size = await client.package('react').size();

// Specific version
const size18 = await client.package('react').size('18.2.0');

console.log(size18.name);            // 'react'
console.log(size18.version);         // '18.2.0'
console.log(size18.size);            // 6457   (minified, bytes)
console.log(size18.gzip);            // 2670   (gzip, bytes)
console.log(size18.dependencyCount); // 2
console.log(size18.hasSideEffects);  // false

// Per-dependency size breakdown
size18.dependencySizes.forEach(d => {
  console.log(`${d.name}: ~${d.approximateSize}B`);
});

Size history

const history = await client.package('react').history();

// history is a Record<version, { size, gzip }>
for (const [version, entry] of Object.entries(history)) {
  console.log(`${version} — ${entry.size}B (${entry.gzip}B gzip)`);
}

Similar packages

const similar = await client.package('react').similar();

similar.alternativePackages.forEach(p => {
  console.log(`${p.name}@${p.version} — ${p.gzip}B gzip`);
});

Chainable resource pattern

PackageResource implements PromiseLike<BundleSize>, so you can await it directly to fetch the latest bundle size or chain methods for specific queries:

// Await directly → latest version bundle size
const size = await client.package('react');

// Chain → specific version
const size18 = await client.package('react').size('18.2.0');

// Chain → history
const history = await client.package('react').history();

Cancelling requests

Pass an AbortSignal to any method to cancel the in-flight request:

const controller = new AbortController();

setTimeout(() => controller.abort(), 3000);

const size    = await client.package('react').size(undefined, controller.signal);
const history = await client.package('react').history(controller.signal);
const similar = await client.package('react').similar(controller.signal);

When a request is aborted, fetch throws a DOMException with name === 'AbortError'. The request event is still emitted with the error attached.

Request events

Subscribe to every HTTP request for logging, monitoring, or debugging:

client.on('request', (event) => {
  console.log(`[${event.method}] ${event.url} → ${event.statusCode} (${event.durationMs}ms)`);
  if (event.error) {
    console.error('Request failed:', event.error.message);
  }
});

The event object contains:

| Field | Type | Description | |-------|------|-------------| | url | string | Full URL that was requested | | method | 'GET' | HTTP method used | | startedAt | Date | When the request started | | finishedAt | Date | When the request finished | | durationMs | number | Duration in milliseconds | | statusCode | number \| undefined | HTTP status code, if a response was received | | error | Error \| undefined | Present only if the request failed |

Multiple listeners can be registered. The event is always emitted after the request completes, whether it succeeded or failed.

Error handling

Non-2xx responses throw a BundlephobiaApiError with the HTTP status code and status text:

import { BundlephobiaApiError } from 'bundlephobia-api-client';

try {
  await client.package('nonexistent-xyz').size();
} catch (err) {
  if (err instanceof BundlephobiaApiError) {
    console.log(err.status);     // 404
    console.log(err.statusText); // 'Not Found'
    console.log(err.message);    // 'Bundlephobia API error: 404 Not Found'
  }
}

TypeScript types

All domain types are exported:

import type {
  // Client
  BundlephobiaClientOptions, RequestEvent, BundlephobiaClientEvents,
  // Bundle size
  BundleSize, BundleAsset, DependencySize,
  // History
  PackageHistory, HistoryEntry,
  // Similar packages
  SimilarPackages, SimilarPackage,
} from 'bundlephobia-api-client';

Documentation

Full API documentation is published at: https://eljijuna.github.io/bundlephobia-api-client

License

MIT