crux-api

library4.1.0jsnpmunverified

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.

http-networking observability

npm install crux-api

github ↗package ↗

INSTALL

IMPORT

SIG · CRUX-API

crux-api

http-networkingjavascriptv4.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createQueryRecord

✓ import { createQueryRecord } from 'crux-api'

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

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

createQueryHistoryRecord

✓ import { createQueryHistoryRecord } from 'crux-api'

✗ 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.

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)

Debug

Known issues

breakingv4.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.

affects: >=4.0.0

breakingv3.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.

affects: >=3.0.0

breakingv2.0.0 drops the batch API. Code using batchQueryRecord will break.

fix

Use individual queryRecord calls for each URL instead of batch.

affects: >=2.0.0

gotchaThe 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.

affects: >=1.0.0

gotchaWhen 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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: createQueryRecord is not a function

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: Quota exceeded (429)

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: Not Found (404)

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 [ERR_REQUIRE_ESM]: require() of ES Module not supported

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

fix

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

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/treosh/crux-api ↗

packagehttps://www.npmjs.com/package/crux-api ↗