@forgedock/fd-fastest-runtime-next

v1.0.0

Published

a month ago

Client-side performance instrumentation for Next.js App Router

0High
0Medium
0Low

domidex

fd-fastest performance web-vitals nextjs react monitoring

@fd-fastest/runtime-next

Client-side performance instrumentation for Next.js App Router applications.

Features

🎯 Web Vitals with Attribution: LCP, CLS, INP with detailed diagnostics
⏱️ Long Task Detection: Capture tasks blocking the main thread
🔄 Route Change Tracking: Automatic marks for navigation events
💧 Hydration Timing: Measure React hydration performance
📊 Zero Configuration: Drop-in component, works out of the box
🪶 Minimal Overhead: < 5KB gzipped, non-blocking collection

Installation

pnpm add @fd-fastest/runtime-next

Usage

Basic Setup

Add the <FDFastMarks /> component to your root layout:

// app/layout.tsx
import { FDFastMarks } from '@fd-fastest/runtime-next';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <FDFastMarks />
        {children}
      </body>
    </html>
  );
}

That's it! The component will automatically collect metrics in the background.

Accessing Collected Data

Data is stored in window.__fdfast.buffer:

// In your browser console or test scripts
import { createLogger } from '@fd-fastest/logger';

const logger = createLogger({ name: 'runtime-buffer' });

logger.debug('Buffered entries', window.__fdfast.buffer);

// Example output:
// [
//   { type: 'lcp', metric: { value: 2400, rating: 'good', ... } },
//   { type: 'cls', metric: { value: 0.05, rating: 'good', ... } },
//   { type: 'longtask', s: 1000, d: 120 },
//   ...
// ]

TypeScript Support

import type {
  LCPEntry,
  CLSEntry,
  AnyBufferEntry,
} from '@fd-fastest/runtime-next';

// Type-safe buffer access
const lcpEntries = window.__fdfast?.buffer.filter(
  (entry): entry is LCPEntry => entry.type === 'lcp'
);

How It Works

Performance Marks

The component creates performance marks for:

fd-fastest:route:[pathname]:start - When route navigation begins
fd-fastest:route:[pathname]:end - When component unmounts
fd-fastest:first-paint:approx - Approximate first paint time
fd-fastest:hydration:end - When React hydration completes

Web Vitals Collection

Uses web-vitals/attribution for detailed diagnostics:

LCP: Captures element, URL, TTFB, resource delays
CLS: Identifies largest shift target and value
INP: Tracks interaction target, type, and timing breakdown

Long Task Detection

Uses PerformanceObserver to capture tasks > 50ms that block the main thread.

API Reference

`FDFastMarks` Component

<FDFastMarks />

No props required. Automatically tracks the current route using Next.js hooks.

Types

interface Window {
  __fdfast?: {
    buffer: AnyBufferEntry[];
    version: string;
  };
}

type AnyBufferEntry =
  | LCPEntry
  | CLSEntry
  | INPEntry
  | LongTaskEntry
  | MarkEntry
  | MeasureEntry;

Browser Support

Modern Browsers: Chrome, Edge, Firefox, Safari (latest 2 versions)
Long Tasks: Chrome, Edge (PerformanceObserver)
Web Vitals: All modern browsers

Falls back gracefully if APIs are not available.

Development

# Build package
pnpm build

# Watch mode
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck

License

MIT