AbsoluteJS

Web Vitals

AbsoluteJS can report Core Web Vitals from real visits. Turn on vitals in absolute.config.ts, and every page sends its metrics to your server, where onVital() hands them to your code.

#Enable

Reporting is off until you set vitals.

TS
// absolute.config.ts
import { defineConfig } from '@absolutejs/absolute';

export default defineConfig({
  reactDirectory: 'src/frontend/react',
  vitals: { sampleRate: 0.25 }
});
OptionDefaultMeaning
endpoint/__absolute/vitalsA path is served by the built-in route. A full URL posts elsewhere.
sampleRate1Share of page loads that report, from 0 to 1.
devfalseReport from absolute dev too.

Each report covers:

LCPLargest Contentful Paint: when the main content shows.
INPInteraction to Next Paint: how fast the page responds to input.
CLSCumulative Layout Shift: how much the layout moves.
FCPFirst Contentful Paint: when anything first shows.
TTFBTime to First Byte: how long the server took to start answering.

#In the Browser

A production build bundles a small reporter, the web-vitals library plus a sender, to /__absolute/vitals/reporter.js. Every framework's client bundle imports it. Static HTML and HTMX pages get a script tag:

HTML
<script type="module" src="/__absolute/vitals/reporter.js" data-absolute-vitals></script>

Each page load decides once whether it reports, using sampleRate. A page that reports collects every metric with its route (the path the page loaded at) and navigation type. It sends them as one batch when the page is hidden or closed, with navigator.sendBeacon, falling back to fetch with keepalive.

With vitals unset, nothing is built or added to pages. absolute dev adds nothing unless dev: true. Pages with client: 'none' ship no client bundle, so they don't report.

The reporter is part of the page, so pre-rendered pages report too. It also works under secureHeaders(): it loads through scripts that carry the nonce, and the default endpoint is on your own origin.

#On the Server

With endpoint set to a path (the default), prepare() serves POST /__absolute/vitals as part of absolutejs. It validates each batch with a TypeBox schema, answers 204, and stores nothing. A batch that fails validation gets a 422.

TXT
POST /__absolute/vitals
Content-Type: application/json

{
  "route": "/pricing",
  "navigationType": "navigate",
  "metrics": [
    { "name": "LCP", "value": 1234, "id": "v5-…", "rating": "good", "delta": 1234 },
    { "name": "CLS", "value": 0.02, "id": "v5-…", "rating": "good", "delta": 0.02 }
  ]
}

#onVital

To keep the metrics, register a handler. It runs once per metric in every batch the endpoint accepts, with the report and the incoming request.

TS
// src/backend/server.ts
import { onVital } from '@absolutejs/absolute';

onVital((report, request) => {
  if (report.rating !== 'poor') return;

  console.warn(
    `[vitals] ${report.name} ${report.value} on ${report.route}`,
    request.headers.get('user-agent')
  );
});
TS
type VitalReport = {
  name: 'CLS' | 'FCP' | 'INP' | 'LCP' | 'TTFB';
  value: number;
  id: string;
  route: string;
  rating?: 'good' | 'needs-improvement' | 'poor';
  delta?: number;
  navigationType?: string;
};

A handler can be async. onVital returns a function that removes the handler. A handler that throws is logged and doesn't affect the response or the other handlers.

TS
const stop = onVital(async (report) => {
  await saveVital(report);
});

// later
stop();

#Remote Endpoint

To send the batches somewhere else, set endpoint to a full URL. The browser posts the same JSON there, and the built-in route isn't mounted, so onVital handlers don't run. The other service must accept a cross-origin JSON POST. Under secureHeaders(), add its origin to connect-src.

TS
// absolute.config.ts
export default defineConfig({
  reactDirectory: 'src/frontend/react',
  vitals: {
    endpoint: 'https://metrics.example.com/vitals',
    sampleRate: 0.1
  }
});

// src/backend/server.ts: the browser now posts to another origin
secureHeaders({
  contentSecurityPolicy: {
    directives: {
      'connect-src': ["'self'", 'https://metrics.example.com']
    }
  }
});