frontend-performance-monitor

This is browser performance and error monitoring tool

Frontend Monitoring SDK Documentation

Overview

The Frontend Monitoring SDK is a lightweight TypeScript library for tracking web application performance metrics and capturing runtime errors. It provides comprehensive monitoring capabilities including Core Web Vitals, resource timing, and error tracking.

Features

• 📊 Performance Monitoring:

  • Navigation Timing metrics
  • Core Web Vitals (LCP, FID, CLS)
  • First Contentful Paint (FCP)
  • First Paint (FP)

• 🚨 Error Tracking:

  • JavaScript runtime errors
  • Resource loading failures
  • Unhandled promise rejections
  • Detailed stack traces

• 📡 Reporting:

  • Beacon API for reliable delivery
  • XMLHttpRequest fallback
  • Simple JSON payload format

Installation

npm install frontend-performance-monitor

import { FrontendMonitor } from 'frontend-performance-monitor';

Usage

Basic Initialization

import { FrontendMonitor } from 'frontend-performance-monitor';

// Initialize with your reporting endpoint
const monitor = new FrontendMonitor('https://api.yourdomain.com/monitor');
monitor.init();

Manual Error Reporting

// Report custom errors
monitor.report({
  type: 'error',
  data: {
    message: 'Authentication timeout',
    filename: 'auth-service.ts',
    lineno: 42,
    colno: 15,
    type: 'js',
    timestamp: Date.now()
  }
});

Performance Tracking

Automatically tracks performance metrics including:

| Metric | Description | Collected Automatically | |--------|-------------|--------------------------| | DNS | DNS lookup time | ✓ | | TCP | TCP connection time | ✓ | | TTFB | Time to First Byte | ✓ | | FCP | First Contentful Paint | ✓ | | LCP | Largest Contentful Paint | ✓ | | CLS | Cumulative Layout Shift | ✓ | | FP | First Paint | ✓ |

API Reference

FrontendMonitor Class

Constructor

new FrontendMonitor(reportUrl: string)

• reportUrl: Endpoint URL for sending monitoring data

Methods

| Method | Parameters | Description | |--------|------------|-------------| | init() | None | Starts monitoring performance and errors | | report(data: ReportData) | data: Performance or error data object | Sends custom monitoring data | | getBasicTiming() | None | Returns calculated performance metrics (internal) |

Data Structures

Performance Report

interface PerformanceReport {
  type: 'performance';
  data: {
    dns: number;      // DNS lookup duration (ms)
    tcp: number;      // TCP connection duration (ms)
    ttfb: number;     // Time to First Byte (ms)
    domParse: number; // DOM parsing duration (ms)
    resources: number; // Resource loading duration (ms)
    domReady: number; // DOM ready time (ms)
    interactive: number; // Time to interactive (ms)
    load: number;     // Page load time (ms)
    fp?: number;      // First Paint (ms)
    fcp?: number;     // First Contentful Paint (ms)
    lcp?: number;     // Largest Contentful Paint (ms)
    fid?: number;     // First Input Delay (ms)
    cls?: number;     // Cumulative Layout Shift
  };
}

Error Report

interface ErrorReport {
  type: 'error';
  data: {
    message: string;  // Error message
    filename: string; // Source file URL
    lineno: number;   // Line number
    colno: number;    // Column number
    stack?: string;   // Stack trace
    type: 'js' | 'resource' | 'promise'; // Error type
    timestamp: number; // Unix timestamp
  };
}

Configuration Options

The SDK works out-of-the-box with no configuration required. For advanced use cases, consider extending the class:

class CustomMonitor extends FrontendMonitor {
  constructor(reportUrl: string) {
    super(reportUrl);
  }

  // Add custom metrics
  reportCustomMetric(metricName: string, value: number) {
    this.report({
      type: 'performance',
      data: {
        ...this.getBasicTiming(),
        [metricName]: value
      }
    });
  }
}

Sample Payloads

Performance Report

{
  "type": "performance",
  "data": {
    "dns": 12,
    "tcp": 25,
    "ttfb": 320,
    "domParse": 42,
    "resources": 150,
    "domReady": 1200,
    "interactive": 850,
    "load": 2100,
    "fp": 980,
    "fcp": 1020,
    "lcp": 1850,
    "cls": 0.15
  }
}

Error Report

{
  "type": "error",
  "data": {
    "message": "Resource load error: https://cdn.example.com/main.css",
    "filename": "https://cdn.example.com/main.css",
    "lineno": 0,
    "colno": 0,
    "type": "resource",
    "timestamp": 1686147200000
  }
}

Browser Compatibility

The SDK supports all modern browsers including:

• Chrome 60+
• Firefox 55+
• Safari 12.1+
• Edge 79+
• Mobile Safari 12.2+

Note: Core Web Vitals (LCP, FID, CLS) require Chrome 77+ or equivalent modern browsers.

Best Practices

1. Endpoint Configuration:

   • Ensure your reporting endpoint accepts CORS requests
   • Add proper authentication if needed
   • Compress responses with gzip

2. Error Filtering:

   // Add before reporting
   if (errorMessage.includes('ThirdPartyScript')) return;

3. User Session Tracking:

   // Add user context
   const sessionId = generateSessionId();
   const blob = new Blob([JSON.stringify({...data, sessionId})], ...);

4. Production Considerations:

   • Add sampling for high-traffic sites
   • Implement rate limiting
   • Add sensitive data filters
   • Include environment tags (production/staging)

Troubleshooting

Common Issues

1. Missing Core Web Vitals:

   • Ensure you're using a supported browser
   • Verify page has sufficient content for LCP calculation

2. CORS Errors:

   Access-Control-Allow-Origin: *
   Access-Control-Allow-Methods: POST
   Access-Control-Allow-Headers: Content-Type

3. Resource Errors Not Captured:

   • Add crossorigin="anonymous" to external scripts/styles
   • Verify server sends proper CORS headers

4. Data Not Reaching Endpoint:

   • Check browser console for network errors
   • Verify endpoint is accepting POST requests
   • Test with XMLHttpRequest fallback

License

This SDK is provided under the MIT License. Use freely in commercial and open-source projects.