FPSentinel

FPSentinel is a lightweight, zero-config frontend performance monitoring SDK. Track real-time FPS, detect frame drops, capture Core Web Vitals, and observe long tasks with minimal overhead.

🚀 Getting Started

Installation

Install the SDK as a development dependency using your preferred package manager:

# npm
npm install fpsentinel

# pnpm
pnpm add fpsentinel

# yarn
yarn add fpsentinel

Quick Start

Initialize FPSentinel with your API key. The SDK automatically starts tracking performance metrics and batches them for efficient delivery.

import { initFPSentinel } from 'fpsentinel';

initFPSentinel({
  apiKey: 'YOUR_API_KEY',
  endpoint: 'https://fpsentinel.satviksharma.in/api/ingest', // Optional: your ingest endpoint
});

[!TIP] You can find your API Key in the Projects page of your FPSentinel Dashboard.

⚙️ Configuration

Customize the SDK behavior with the following options:

initFPSentinel({
  apiKey: 'fps_live_...',        // Required: Your project API key
  endpoint: '/api/ingest',       // Custom ingest endpoint (default: '/api/ingest')
  batchSize: 50,                 // Max events per batch (default: 50)
  batchInterval: 5000,           // Send frequency in ms (default: 5000)
  trackFps: true,                // Enable FPS tracking (default: true)
  trackFrameDrops: true,         // Enable frame drop detection (default: true)
  trackWebVitals: true,          // Enable Web Vitals (LCP, CLS, INP, FCP, TTFB)
  trackLongTasks: true,          // Enable JS long task detection
  frameDropThreshold: 50,        // Threshold for frame drop in ms (default: 50)
  fpsReportInterval: 5000,       // FPS calculation window in ms (default: 5000)
  fpsChangeThreshold: 2,         // Only report FPS if changed by X (default: 2)
});

Options API

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Required. Your project API key. | | endpoint | string | '/api/ingest' | The URL where performance data is sent. | | batchSize | number | 50 | Maximum number of events to include in one API call. | | batchInterval | number | 5000 | How often to flush the event queue (in milliseconds). | | trackFps | boolean | true | Whether to monitor Frames Per Second. | | trackFrameDrops | boolean | true | Whether to detect individual dropped frames (jank). | | trackWebVitals | boolean | true | Capture LCP, CLS, INP, FCP, and TTFB. | | trackLongTasks | boolean | true | Detect JavaScript execution blocking the main thread. | | frameDropThreshold| number | 50 | Delta in ms to consider a frame "dropped". | | fpsReportInterval | number | 5000 | Interval to calculate and report average FPS. | | fpsChangeThreshold| number | 2 | Minimum FPS delta required to trigger a report. |

✨ Features

📊 FPS Tracking

Monitors the smoothness of your UI by calculating Frames Per Second using requestAnimationFrame. To save bandwidth, it only reports when a "meaningful change" (default ±2 FPS) is detected.

📉 Frame Drop & Jank

Detects individual frames that take longer than your threshold (default 50ms) to render. High frame drop counts correlate directly with perceived "jank" or "stutter".

⚡ Core Web Vitals

Automatically captures critical performance metrics as defined by Google:

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

🧵 Long Tasks

Uses the PerformanceObserver API to detect when JavaScript execution blocks the main thread for more than 50ms, helping you identify performance bottlenecks in your code.

📦 Event Batching

Events are stored in memory and dispatched every 5 seconds (configurable) using navigator.sendBeacon (with a fetch fallback). This ensures zero impact on your application's main thread and page load performance.

🛡️ License

MIT © FPSentinel. Made with ❤️ by Satvik Sharma