rpalert-sdk
v0.2.0
Published
Lightweight React performance monitoring SDK for RPAlert
Maintainers
yositechReadme
rpalert-sdk
Lightweight React performance monitoring SDK for RPAlert.
👉 Get your free API key at rpalert.dev
Features
- 📊 Monitor Web Vitals (LCP, FCP, CLS, INP)
- 🔍 LCP element identification (tagName, resource URL, load time)
- 📱 Client context (device type, network, screen size)
- ⚡ Detect Long Tasks (>50ms)
- 🔔 Automatic Discord/Slack notifications when performance degrades
- 📦 <5KB gzipped, zero dependencies
- 🎯 Simple API
Installation
npm install rpalert-sdk
# or
pnpm add rpalert-sdk
# or
yarn add rpalert-sdkUsage
Vanilla / manual
import RPAlert from "rpalert-sdk";
// Start monitoring
RPAlert.start("your-api-key");
// Stop monitoring
RPAlert.stop();
// Enable debug mode
RPAlert.setDebug(true);React wrapper (recommended)
Use RPAlertProvider to automatically start and stop monitoring with your React component lifecycle. The ideal place is your root layout.tsx.
// app/layout.tsx
import { RPAlertProvider } from 'rpalert-sdk/react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<RPAlertProvider apiKey={process.env.NEXT_PUBLIC_RPALERT_API_KEY!}>
{children}
</RPAlertProvider>
</body>
</html>
);
}Monitoring starts on mount and stops on unmount — no manual cleanup required.
Configuration
import { start } from "rpalert-sdk";
start("your-api-key", {
endpoint: "https://rpalert.dev/api/metrics", // API endpoint (optional)
debug: false, // Enable debug logging (optional)
batchInterval: 30000, // Batch interval in ms (optional)
});Configuration options
| Field | Type | Default | Description |
| --------------- | --------- | ----------------------------------- | -------------------------------------------------- |
| apiKey | string | — | Required. Your RPAlert API key. |
| endpoint | string | "https://rpalert.dev/api/metrics" | Metrics ingestion endpoint. |
| debug | boolean | false | Log debug information to the console. |
| batchInterval | number | 30000 | Interval (ms) at which collected metrics are sent. |
TypeScript types
interface RPAlertConfig {
apiKey: string;
endpoint?: string;
debug?: boolean;
batchInterval?: number; // milliseconds, default: 30000
}
interface PerformanceMetrics {
lcp?: number; // Largest Contentful Paint (seconds)
fcp?: number; // First Contentful Paint (seconds)
cls?: number; // Cumulative Layout Shift (unitless score)
longTasks: number; // Number of long tasks (>50ms) detected
uiEvents: number;
page: string;
userAgent: string;
timestamp: number;
}LCP element identification
The SDK automatically collects details about the LCP element, helping you pinpoint what's causing slow page loads:
- tagName: The HTML element type (e.g.,
img,h1,div) - url: Resource URL for images/videos
- loadTime: How long the resource took to load (ms)
- size: Rendered size of the element
- component: React component name via
data-componentattribute
Using data-component
Add data-component to your React components to see component names in alerts:
function HeroBanner() {
return (
<div data-component="HeroBanner">
<img src="/hero.webp" alt="Hero" />
</div>
);
}When this element is the LCP, your Discord/Slack alert will show Component: HeroBanner, making it easy to find and fix the issue.
Getting your API key
- Sign up or log in at rpalert.dev
- Navigate to the Apps page
- Create a new app — your API key is shown once after creation
- Copy and store it securely (e.g. as
NEXT_PUBLIC_RPALERT_API_KEYin.env.local)
License
MIT