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.
// absolute.config.ts
import { defineConfig } from '@absolutejs/absolute';
export default defineConfig({
reactDirectory: 'src/frontend/react',
vitals: { sampleRate: 0.25 }
});| Option | Default | Meaning |
|---|---|---|
endpoint | /__absolute/vitals | A path is served by the built-in route. A full URL posts elsewhere. |
sampleRate | 1 | Share of page loads that report, from 0 to 1. |
dev | false | Report from absolute dev too. |
Each report covers:
#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:
<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.
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.
// 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')
);
});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.
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.
// 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']
}
}
});