crux-api

4.1.0 verified Sat May 09 auth: no javascript

A tiny (~500 bytes) CrUX API wrapper supporting both record and history APIs, with TypeScript types, automatic retry on rate limits, and URL normalization. Current stable version: 4.1.0. Release cadence: irregular, with major versions for breaking changes (ESM conversion in v3, dropping effectiveConnectionType in v4). Key differentiators: isomorphic (browser + Node.js), returns null on 404, handles 429 with retries, and provides TypeScript definitions for API responses. Alternatives require manual fetch handling and lack type safety.

Common errors

error TypeError: createQueryRecord is not a function ↓

cause Importing the default export instead of named export, or using CommonJS with ESM-only library (v3+).

fix

Use named import: import { createQueryRecord } from 'crux-api'

error Error: Quota exceeded (429) ↓

cause Exceeded CrUX API daily quota or rate limit.

fix

Wait for quota reset or reduce request frequency. The library retries automatically on 429, but if retries are exhausted, you may need to upgrade your API plan.

error Error: Not Found (404) ↓

cause The requested URL is not in CrUX data or is invalid.

fix

The library returns null for 404; handle null gracefully. Ensure URL is normalized (use normalizeUrl).

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using require() on a package that is ESM-only (v3+).

fix

Use import syntax or dynamic import(): const mod = await import('crux-api')

Warnings

breaking v4.0.0 drops effectiveConnectionType support (deprecated by CrUX API). If you rely on connectivity data, you must remove related code. ↓

fix Remove effectiveConnectionType parameter from queries; it is no longer supported by CrUX API.

breaking v3.0.0 converts the package to ES module. require() will not work; you must use import syntax. ↓

fix Use ES module imports (import { createQueryRecord } from 'crux-api') or switch to dynamic import.

breaking v2.0.0 drops the batch API. Code using batchQueryRecord will break. ↓

fix Use individual queryRecord calls for each URL instead of batch.

gotcha The API key (CRUX_API_KEY) is required. If not provided, requests will fail with a 403 error. ↓

fix Pass a valid key to createQueryRecord or createQueryHistoryRecord.

gotcha When URL is not found in CrUX data, the library returns null (not an error). This can silently skip missing data if not checked. ↓

fix Always check for null return before accessing properties.

Install

npm install crux-api

yarn add crux-api

pnpm add crux-api

Imports

createQueryRecord

wrong

const { createQueryRecord } = require('crux-api')

correct

import { createQueryRecord } from 'crux-api'

ESM-only since v3. CommonJS require is not supported.

createQueryHistoryRecord

wrong

import createQueryHistoryRecord from 'crux-api'

correct

import { createQueryHistoryRecord } from 'crux-api'

Named export, not default. Use named import.

normalizeUrl
```
import { normalizeUrl } from 'crux-api'
```
Helper to normalize URLs for CrUX API indexing.

Quickstart

Creates queryRecord and queryHistoryRecord instances with an API key, fetches CrUX data for a URL, and normalizes URLs.

import { createQueryRecord, createQueryHistoryRecord } from 'crux-api'

const CRUX_API_KEY = process.env.CRUX_API_KEY ?? ''

const queryRecord = createQueryRecord({ key: CRUX_API_KEY })
const queryHistory = createQueryHistoryRecord({ key: CRUX_API_KEY })

async function main() {
  // Fetch record data
  const record = await queryRecord({ url: 'https://example.com' })
  console.log('Record:', record)

  // Fetch history data
  const history = await queryHistory({ url: 'https://example.com' })
  console.log('History:', history)

  // Normalize a URL
  const normalized = normalizeUrl('https://example.com/path?query=1#hash')
  console.log('Normalized:', normalized)
}

main().catch(console.error)