Web Vitals Recorder

A lightweight package for recording web vitals in real time for any web project. This package provides an easy way to capture and send web performance metrics to a specified endpoint.

Features

• Real-time logging of Core Web Vitals (INP, LCP)
• Option to log metrics to the browser console or send them to a remote endpoint
• Uses native browser APIs (PerformanceObserver, Event Timing API)
• Detailed breakdown of INP events (input delay, processing duration, presentation delay)
• Easily extensible for additional metrics

How It Works

The recorder hooks into browser APIs to listen for relevant performance events. When a metric is captured, it is either logged to the console or sent to a configured endpoint for further analysis.

Installation

You can install the package via npm:

npm install web-vitals-recorder

Usage

To use the Web Vitals Recorder, you need to import it and initialize it in your project. Here’s a simple example:

import { Recorder } from 'web-vitals-recorder';

const recorder = new Recorder({
    endpoint: 'https://your-endpoint.com/metrics',     // necessary only when outputType is endpoint, else throws error
    outputType: 'console'   // Either console or endpoint   
    // "console"  prints it in the browser's console
    // "endpoint" sends the data to the endpoint via provided endpoint
});



// Start recording web vitals
recorder.startMeasuringINP();   // To measure INP
recorder.startMeasuringLCP();   // To measure LCP

// Stop recording after a certain period
    recorder.stopMeasuringINP();

Metrics Captured

• INP (Interaction to Next Paint): Measures the latency of user interactions, with a breakdown of input delay, processing duration, and presentation delay.
• LCP (Largest Contentful Paint): Measures loading performance by reporting the render time of the largest content element visible in the viewport.

API

Recorder

constructor(options: RecorderOptions)

Creates a new instance of the Recorder.

• options: An object that contains configuration options for the recorder.

startMeasuringINP()

Starts capturing INP metrics.

stopMeasuringINP()

Stops capturing INP metrics.

startMeasuringLCP()

Starts capturing LCP metrics.

Types

RecorderOptions

An interface that defines the options for configuring the recorder.

WebVitalMetrics

An interface that defines the structure of the web vitals metrics being captured.

Requirements

• Modern browser (Chrome, Edge, etc.) with support for PerformanceObserver and Event Timing API
• Node.js (for development and building, if applicable)

License

This project is licensed under the MIT License. See the LICENSE file for more details.

Web Vitals Recorder helps you gain actionable insights into your web app’s performance, enabling you to deliver a faster and more responsive user experience.