npm package: @forgedock/fd-fastest-runtime-next
Description: Client-side performance instrumentation for Next.js App Router
Author: ForgeDock
Latest version: 1.0.0

# @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

```bash
pnpm add @fd-fastest/runtime-next
```

## Usage

### Basic Setup

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

```tsx
// 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`:

```typescript
// 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

```typescript
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

```tsx
<FDFastMarks />
```

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

### Types

```typescript
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

```bash
# Build package
pnpm build

# Watch mode
pnpm dev

# Run tests
pnpm test

# Type check
pnpm typecheck
```

## License

MIT