BundleCheck

Analyze npm package bundle size with deterministic output and fast cached responses.

Built by VenMode Labs
Links
API DocsAboutAPI statusRequest beta keyContactPrivacyTerms
Connect
[email protected]
—
    Back to checker

    API Documentation

    Use our REST API to check npm package bundle sizes programmatically.

    Quick Start

    Check the bundle size of any npm package with a simple GET request (API key required):

    bash
    curl -H "X-API-Key: $BUNDLECHECK_API_KEY" "https://bundlecheck.dev/v1/api/size?package=zustand"
    
    # With specific version
    curl -H "X-API-Key: $BUNDLECHECK_API_KEY" "https://bundlecheck.dev/v1/api/size?package=zustand&version=4.5.0"
    
    # With dist-tag
    curl -H "X-API-Key: $BUNDLECHECK_API_KEY" "https://bundlecheck.dev/v1/api/size?package=react&version=latest"

    Endpoints

    GET
    /v1/api/size

    Get bundle size for an npm package.

    Query Parameters

    package
    required
    Package name (e.g., react, @types/node)
    version
    optional
    Version or dist-tag (e.g., 4.5.0, latest, next). Defaults to latest.

    Success Response (200 OK)

    json
    {
      "package": "zustand",
      "version": "5.0.10",
      "tag": "latest",
      "fetchedAt": "2026-02-11T21:30:00.000Z",
      "cached": true,
      "sizes": {
        "raw": 52341,
        "minified": 23456,
        "gzip": 8234,
        "brotli": 7123
      }
    }

    Response Fields

    packagePackage name as resolved from npm
    versionExact version that was bundled
    tagOriginal dist-tag if used (e.g., "latest", "next")
    fetchedAtISO 8601 timestamp of result
    cachedWhether result was served from cache
    sizes.rawUnprocessed bundle size in bytes
    sizes.minifiedMinified bundle size in bytes
    sizes.gzipMinified + gzip compressed size in bytes
    sizes.brotliMinified + brotli compressed size in bytes
    GET
    /v1/api/status

    Get API health and uptime statistics.

    Success Response (200 OK)

    json
    {
      "status": "healthy",
      "timestamp": "2026-02-11T21:30:00.000Z",
      "uptime": {
        "periodDays": 7,
        "successRate": 0.9876,
        "successRatePercent": 98.76,
        "totalRequests": 12543,
        "successfulRequests": 12388
      }
    }

    Error Responses

    All errors follow a consistent format:

    json
    {
      "error": {
        "code": "ERROR_CODE",
        "message": "Human-readable error message",
        "details": {
          // Optional additional context
        }
      }
    }

    Error Codes

    INVALID_INPUT
    Missing or invalid query parameters (400)
    PACKAGE_NOT_FOUND
    Package does not exist on npm (404)
    VERSION_NOT_FOUND
    Specified version does not exist (404)
    BUNDLE_FAILED
    Package could not be bundled (500)
    PACKAGE_TOO_LARGE
    Package exceeds size limits (413)
    RATE_LIMITED
    Too many requests, includes retryAfter in details (429)
    INTERNAL_ERROR
    Unexpected server error (500)
    Rate Limits

    Requests are rate-limited per IP address (or API key). If you exceed a limit you'll receive a RATE_LIMITED error with a retryAfter value (in seconds) indicating when to retry.

    WindowLimitNotes
    10 seconds10 requestsBurst — prevents scripted abuse
    1 hour300 requests~5 req/min sustained
    24 hours3,000 requestsSuitable for CI pipelines

    Need higher limits? Request a beta key for a dedicated rate limit bucket.

    Code Examples

    JavaScript / TypeScript

    typescript
    // Using fetch
    const response = await fetch(
      "https://bundlecheck.dev/v1/api/size?package=react&version=latest",
      {
        headers: {
          "X-API-Key": process.env.BUNDLECHECK_API_KEY!,
        },
      }
    );
    const data = await response.json();
    
    if (!response.ok) {
      console.error("Error:", data.error.message);
    } else {
      console.log(`Bundle size: ${data.sizes.gzip} bytes (gzipped)`);
    }
    
    // Using axios
    import axios from "axios";
    
    try {
      const { data } = await axios.get(
        "https://bundlecheck.dev/v1/api/size",
        {
          params: { package: "zustand", version: "4.5.0" },
          headers: {
            "X-API-Key": process.env.BUNDLECHECK_API_KEY!,
          },
        }
      );
      console.log("Sizes:", data.sizes);
    } catch (error) {
      if (axios.isAxiosError(error)) {
        console.error("API Error:", error.response?.data.error);
      }
    }

    Python

    python
    import os
    import requests
    
    response = requests.get(
        "https://bundlecheck.dev/v1/api/size",
        params={"package": "react", "version": "latest"},
        headers={"X-API-Key": os.environ["BUNDLECHECK_API_KEY"]},
    )
    
    if response.status_code == 200:
        data = response.json()
        print(f"Gzip size: {data['sizes']['gzip']} bytes")
    else:
        error = response.json()["error"]
        print(f"Error: {error['message']}")

    Go

    go
    package main
    
    import (
        "encoding/json"
        "fmt"
        "net/http"
        "net/url"
        "os"
    )
    
    type SizeResult struct {
        Package  string `json:"package"`
        Version  string `json:"version"`
        Sizes    struct {
            Gzip int `json:"gzip"`
        } `json:"sizes"`
    }
    
    func main() {
        baseURL := "https://bundlecheck.dev/v1/api/size"
        params := url.Values{}
        params.Add("package", "zustand")
        params.Add("version", "latest")
    
        req, err := http.NewRequest(http.MethodGet, baseURL+"?"+params.Encode(), nil)
        if err != nil {
            panic(err)
        }
        req.Header.Set("X-API-Key", os.Getenv("BUNDLECHECK_API_KEY"))
    
        resp, err := http.DefaultClient.Do(req)
        if err != nil {
            panic(err)
        }
        defer resp.Body.Close()
    
        var result SizeResult
        json.NewDecoder(resp.Body).Decode(&result)
        fmt.Printf("Gzip size: %d bytes\n", result.Sizes.Gzip)
    }
    Best Practices
    • Cache responses: Results are stable for a given package@version combination. Cache them on your end.
    • Use exact versions: Specify exact versions instead of tags for reproducible results.
    • Handle errors gracefully: Check error codes and provide fallbacks.
    • Respect rate limits: Implement exponential backoff when rate-limited.
    • Monitor cached field: Track cache hit rates to optimize your usage patterns.

    Have questions or need help? Contact us or request beta access or send feedback.