@fd-fastest/reporter-json

Type-safe schemas for FD-Fastest performance reports built with Zod.

Installation

pnpm add @fd-fastest/reporter-json

Usage

Basic Validation

import { Report, RouteMetric } from '@fd-fastest/reporter-json';
import { createLogger } from '@fd-fastest/logger';

const logger = createLogger({ name: 'report-json-example' });

// Validate a complete report
const report = Report.parse(data); // Throws if invalid

// Safe parsing (doesn't throw)
const result = Report.safeParse(data);
if (result.success) {
  logger.info('Valid report', { report: result.data });
} else {
  logger.error({ err: result.error }, 'Validation errors');
}

Creating Reports

import {
  Report,
  RouteMetric,
  REPORT_SPEC_VERSION,
} from '@fd-fastest/reporter-json';

const report: Report = {
  spec_version: REPORT_SPEC_VERSION,
  app: 'my-nextjs-app',
  git: {
    sha: 'abc123',
    branch: 'main',
  },
  run: {
    ts: new Date().toISOString(),
    device: 'desktop',
    network: 'fast-3g',
    cpuSlowdown: 4,
  },
  routes: [
    {
      path: '/',
      nav: 'cold',
      lcp_ms: 2400,
      cls: 0.05,
      inp_ms: 150,
      tbt_ms: 180,
      tti_ms: 3200,
      hydration_ms: 450,
      long_tasks: [],
      js_kb: 145,
      css_kb: 25,
      assets_top: [],
      notes: [],
    },
  ],
  budgets: {
    lcp_ms: 2500,
    cls: 0.1,
    regression_cap_pct: 10,
  },
  budgets_passed: true,
  budget_failures: [],
  psi: undefined,
};

// Validate and ensure type safety
Report.parse(report);

Schemas

RouteMetric

Performance metrics for a single route measurement.

• path: Route pathname
• nav: Navigation type ('cold', 'warm', 'client-nav')
• lcp_ms: Largest Contentful Paint
• cls: Cumulative Layout Shift
• inp_ms: Interaction to Next Paint
• tbt_ms: Total Blocking Time
• tti_ms: Time to Interactive
• hydration_ms: React hydration time
• long_tasks: Array of blocking tasks > 50ms
• js_kb: JavaScript bundle size (gzipped)
• css_kb: CSS bundle size (gzipped)
• assets_top: Top 10 largest assets
• notes: Additional notes

Budgets

Performance budget thresholds.

• lcp_ms: Maximum LCP
• cls: Maximum CLS
• inp_ms: Maximum INP
• tbt_ms: Maximum TBT
• js_kb_route_max: Maximum JS per route
• css_kb_route_max: Maximum CSS per route
• regression_cap_pct: Maximum regression % from baseline (default: 10)

Report

Complete performance report.

• spec_version: Schema version
• app: Application name
• git: Git context
• run: Test run metadata
• routes: Array of route metrics
• budgets: Budget configuration
• budgets_passed: Budget check result
• budget_failures: Failed checks
• psi: Optional PageSpeed Insights data

License

MIT