Skip to content

Latest commit

 

History

History
160 lines (118 loc) · 3.73 KB

README.md

File metadata and controls

160 lines (118 loc) · 3.73 KB

Kruk - Chrome UX Report (CrUX) CLI Tool

Kruk is a command-line interface tool that helps you fetch and visualize Chrome User Experience Report (CrUX) data for websites. It provides easy access to real-world performance metrics collected from Chrome users.

Installation

npm install -g kruk

Usage

Basic syntax:

kruk --key YOUR_API_KEY --urls URL1,URL2 [options]

Required Parameters

  • --key: Your Google API key (Get it from Google Cloud Console)
  • --urls: Comma-separated list of URLs to analyze

Optional Parameters

  • --formFactor: Device type to filter results (default: 'PHONE')
    • Options: 'ALL_FORM_FACTORS', 'DESKTOP', 'TABLET', 'PHONE'
  • --ect: Effective Connection Type
    • Options: 'offline', 'slow-2G', '2G', '3G', '4G'
  • --checkOrigin: Get data for the entire origin instead of specific URLs
  • --history: Use CrUX history API to get historical data
  • --output: Output format (default: 'table')
    • Options: 'distribution', 'json', 'csv', 'table'

Examples

  1. Basic usage with multiple URLs:
kruk --key YOUR_API_KEY --urls www.google.com,www.bing.com
  1. Check specific connection type:
kruk --key YOUR_API_KEY --urls www.google.com,www.bing.com --ect 4G
  1. Check desktop metrics:
kruk --key YOUR_API_KEY --urls www.google.com,www.bing.com --formFactor DESKTOP
  1. Get origin-level data:
kruk --key YOUR_API_KEY --urls www.google.com --checkOrigin
  1. Get data for tablet users on 3G:
kruk --key YOUR_API_KEY --urls www.google.com,www.bing.com --formFactor TABLET --ect 3G

Output Metrics

The tool provides data for the following Core Web Vitals and additional metrics:

  • CLS (Cumulative Layout Shift)
  • FCP (First Contentful Paint)
  • LCP (Largest Contentful Paint)
  • TTFB (Time to First Byte)
  • INP (Interaction to Next Paint)

Output Formats

  1. Table (default): Displays data in a formatted table
  2. Distribution: Shows visual distribution of metrics using unicode characters
  3. CSV: Outputs data in CSV format for further processing
  4. JSON: Raw JSON output of the data

Programmatic Usage

Kruk can also be used as a module in your Node.js applications.

Installation

npm install kruk

Basic Usage

import { getReports } from "kruk";

async function fetchCruxData() {
  const urls = ["www.google.com", "www.bing.com"];
  const API_KEY = "YOUR_API_KEY";

  const params = {
    effectiveConnectionType: "4G", // optional
    formFactor: "PHONE", // optional
    origin: false, // optional, set true for origin-level data
    history: false, // optional, set true for historical data
  };

  try {
    const data = await getReports(urls, API_KEY, params);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

Response Structure

The response will include metrics data in the following format:

{
  params: {
    // Query parameters used
  },
  metrics: [
    {
      url: "https://www.example.com",
      CLS: {
        p75: number,
        rank: "good" | "average" | "poor",
        histogram: [number, number, number] // Distribution values
      },
      FCP: {
        // Similar structure as CLS
      },
      LCP: {
        // Similar structure as CLS
      },
      TTFB: {
        // Similar structure as CLS
      },
      INP: {
        // Similar structure as CLS
      }
    }
  ]
}

Requirements

  • Node.js
  • Google API Key with access to Chrome UX Report API

Note

The tool requires a valid Google API key with access to the Chrome UX Report API. Make sure to handle the API key securely and not share it in public repositories.