@pwa-reliability/guardian-sdk

v1.0.1

Published

24 days ago

Real-time Web Performance Monitoring SDK with Auto-Healing capabilities

0High
0Medium
0Low

chris311420

performance monitoring web-vitals rum real-user-monitoring auto-healing error-tracking pwa performance-optimization

@performance-guardian/sdk

Real-time Web Performance Monitoring with Auto-Healing

Official NPM package for Performance Guardian SDK. Monitor Web Vitals, track errors, and automatically heal performance issues in production.

Features

✅ Web Vitals Tracking - Monitor LCP, FID, CLS, TTFB, INP, FCP ✅ Error Monitoring - Track JavaScript errors with stack traces ✅ Performance Metrics - Real-time performance analytics ✅ Auto-Healing - Automatically fix critical issues (Enterprise) ✅ Zero Dependencies - Lightweight and fast ✅ TypeScript - Full type safety

Installation

npm install @performance-guardian/sdk
# or
yarn add @performance-guardian/sdk
# or
pnpm add @performance-guardian/sdk

Quick Start

Vanilla JavaScript

import { Guardian } from '@performance-guardian/sdk';

const guardian = new Guardian({
  apiUrl: 'https://your-api-url.com',
  siteId: 'your-site-id',
  apiKey: 'your-api-key',
  trackWebVitals: true,
  trackErrors: true,
  autoHeal: false, // Enterprise only
});

guardian.init();

React

import { GuardianProvider } from '@performance-guardian/sdk/react';

function App() {
  return (
    <GuardianProvider
      config={{
        apiUrl: 'https://your-api-url.com',
        siteId: 'your-site-id',
        apiKey: 'your-api-key',
      }}
    >
      <YourApp />
    </GuardianProvider>
  );
}

Next.js (App Router)

// app/layout.tsx
import { GuardianScript } from '@performance-guardian/sdk/nextjs';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GuardianScript
          config={{
            apiUrl: process.env.NEXT_PUBLIC_GUARDIAN_URL,
            siteId: process.env.NEXT_PUBLIC_GUARDIAN_SITE_ID,
            apiKey: process.env.NEXT_PUBLIC_GUARDIAN_API_KEY,
          }}
        />
        {children}
      </body>
    </html>
  );
}

Configuration

interface GuardianConfig {
  // Required
  apiUrl: string;
  siteId: string;
  apiKey: string;

  // Optional
  trackWebVitals?: boolean; // Default: true
  trackErrors?: boolean; // Default: true
  trackPerformance?: boolean; // Default: true
  trackEvents?: boolean; // Default: true
  autoHeal?: boolean; // Default: false (Enterprise only)
  reportInterval?: number; // Default: 30000 (30 seconds)
  debug?: boolean; // Default: false
  sampleRate?: number; // Default: 1.0 (100%)
}

API

Guardian Class

import { Guardian } from '@performance-guardian/sdk';

const guardian = new Guardian(config);

// Initialize tracking
guardian.init();

// Track custom event
guardian.trackEvent('user_action', { action: 'click', target: 'button' });

// Track custom metric
guardian.trackMetric('custom_metric', 123);

// Report error manually
guardian.reportError(new Error('Something went wrong'), { context: 'user_action' });

// Stop tracking
guardian.stop();

Web Vitals

Automatically tracked:

LCP (Largest Contentful Paint) - Loading performance
FID (First Input Delay) - Interactivity
CLS (Cumulative Layout Shift) - Visual stability
TTFB (Time to First Byte) - Server response time
INP (Interaction to Next Paint) - Responsiveness
FCP (First Contentful Paint) - Initial render

Error Tracking

Automatically captures:

Uncaught JavaScript errors
Unhandled promise rejections
Stack traces with source maps
Error context and metadata

Auto-Healing (Enterprise)

Automatically fixes:

Service Worker failures
Cache corruption
Network timeouts
Resource loading issues

Environment Variables

# .env.local
NEXT_PUBLIC_GUARDIAN_URL=https://pwa-command-center.vercel.app
NEXT_PUBLIC_GUARDIAN_SITE_ID=your-site-id
NEXT_PUBLIC_GUARDIAN_API_KEY=pg_your-api-key

TypeScript

Full TypeScript support included:

import type { GuardianConfig, GuardianInstance } from '@performance-guardian/sdk';

const config: GuardianConfig = {
  apiUrl: 'https://your-api-url.com',
  siteId: 'your-site-id',
  apiKey: 'your-api-key',
};

const guardian: GuardianInstance = new Guardian(config);

Browser Support

Chrome/Edge 90+
Firefox 88+
Safari 14+
Opera 76+

License

Support

📧 Email: [email protected]
🐛 Issues: https://github.com/pwa-reliability/guardian-sdk/issues
📖 Docs: https://pwa-reliability.com/docs
💬 Discord: https://discord.gg/pwa-reliability

Changelog

See CHANGELOG.md for version history.

Made with ❤️ by PWA Reliability