render-telemetry-corestable

Typed event protocol and observability infrastructure — emit structured telemetry events from any React component, buffer them with useSyncExternalStore, and pipe them to custom transports. Zero dependencies, no React peer dep.

Install: pnpm add @sapanmozammel/render-telemetry-core

✓ healthy

A component with stable props is re-rendered by its parent. No prop-change event is emitted — only session-start, render, frequency, score, and recommendation. Watch the sequenceNumber increment monotonically.

<DemoTarget>render #1

title"Dashboard"

count0

Event stream (TelemetryBuffer)

Trigger an action above.No output = no events emitted yet.

▸See the code

import {
  createTelemetryBuffer,
  createTelemetrySession,
  createSessionStartEvent,
  createRenderEvent,
  endTelemetrySession,
  createSessionEndEvent,
} from '@sapanmozammel/render-telemetry-core';
import { useSyncExternalStore, useEffect, useRef } from 'react';

// 1. Create buffer and session
const buffer = createTelemetryBuffer();
let session = createTelemetrySession('DemoTarget');

// 2. Emit session-start
const { event: startEv, session: s1 } = createSessionStartEvent(session);
session = s1;
buffer.push(startEv);
buffer.pushSession(session);

// 3. Subscribe to buffer for live display
const snapshot = useSyncExternalStore(
  buffer.subscribe,
  buffer.getSnapshot,
  buffer.getServerSnapshot,
);

// 4. Emit render event on each render
const { event: renderEv, session: s2 } = createRenderEvent(session, {
  renderNumber: 1,
  triggeredBy: 'parent',
});
session = s2;
buffer.push(renderEv);
buffer.updateSession(session);

// 5. End session on unmount
useEffect(() => {
  return () => {
    const ended = endTelemetrySession(session);
    const { event: endEv } = createSessionEndEvent(ended, { totalRenders: 1 });
    buffer.push(endEv);
    buffer.updateSession(ended);
  };
}, []);

▸How to use render-telemetry-core

import {
  createTelemetryBuffer,
  createTelemetrySession,
  createSessionStartEvent,
  createRenderEvent,
  endTelemetrySession,
  createSessionEndEvent,
  registerTransport,
  createMemoryTransport,
  emitEvents,
} from '@sapanmozammel/render-telemetry-core';
import { useSyncExternalStore } from 'react';

// 1. Register a transport (once, app-level)
const transport = createMemoryTransport();
registerTransport(transport);

// 2. In your component (or custom hook):
const buffer = createTelemetryBuffer();
let session = createTelemetrySession('MyComponent');

// 3. On mount: emit session-start
const { event: startEv, session: s1 } = createSessionStartEvent(session);
session = s1;
buffer.push(startEv);
buffer.pushSession(session);
emitEvents([startEv]);

// 4. On each render: emit render + other events
const { event: renderEv, session: s2 } = createRenderEvent(session, {
  renderNumber: 1,
  triggeredBy: 'props',
});
session = s2;
buffer.push(renderEv);
buffer.updateSession(session);
emitEvents([renderEv]);

// 5. Subscribe to buffer for live display
const snapshot = useSyncExternalStore(
  buffer.subscribe,
  buffer.getSnapshot,
  buffer.getServerSnapshot,
);
// snapshot.events — live event log
// snapshot.sessions — all active sessions

Zero production cost: this package has no built-in NODE_ENV guard. Only create sessions where you want telemetry — your wrapper hook decides when.