repository·main·Indexed 27 days ago
https://github.com/googlechrome/web-vitalsA lightweight, modular JavaScript library used to measure Web Vitals metrics such as CLS, INP, and LCP on real users. It provides data that matches Chrome and Google performance tools, offering both standard and attribution builds for diagnostic information. The library supports installation via npm, CDN (ES modules or classic scripts), and includes features for reporting metric deltas, soft navigations for SPAs, and integration with analytics endpoints like Google Analytics 4.
The following tools integrate with web-vitals data:
web-vitals-reporter: A JavaScript library designed to batch callback functions and send data in a single request.LCPAttribution property resourceLoadTime has been renamed to resourceLoadDuration.webdriver.io to test metrics in real browsers. You can run the full test suite or start a local test server to manually verify APIs using provided templates.When upgrading to v4, the TTFBAttribution object properties have been renamed to reflect durations rather than absolute times, and a new cache metric has been added.
Renamed Properties:
waitingTime $\rightarrow$ waitingDurationdnsTime $\rightarrow$ dnsDurationconnectionTime $\rightarrow$ connectionDurationrequestTime $\rightarrow$ requestDurationNew Properties in v4:
cacheDuration: Total time spent checking the HTTP cache for a match.The web-vitals package provides different build types depending on your integration needs.
| Filename | Export | Description |
|---|---|---|
web-vitals.js | pkg.module | ES module bundle (Standard build). |
web-vitals.umd.cjs | pkg.main | UMD version of the standard bundle (exposed on self.webVitals.*). |
web-vitals.iife.js | -- | IIFE version of the standard bundle (exposed on self.webVitals.*). |
web-vitals.attribution.js | -- | ES module version including attribution features. |
web-vitals.attribution.umd.cjs | -- | UMD version of the attribution build (exposed on self.webVitals.*). |
web-vitals.attribution.iife.js | -- | IIFE version of the attribution build (exposed on self.webVitals.*). |
Most developers should use the Standard Build via either the ES module or UMD version, depending on their bundler or build system.
In the attribution build, you can provide a generateTarget function in AttributionReportOpts. This allows you to customize how DOM elements are stringified for reporting (e.g., using a custom data-name attribute instead of default CSS selectors).
function customGenerateTarget(el) {
if (el.dataset.name) {
return el.dataset.name;
}
// Otherwise use default selector function
}
onLCP(sendToAnalytics, {generateTarget: customGenerateTarget});You can load web-vitals using a classic <script> tag. When using this method, all public methods are available on the webVitals global namespace.
Standard build example:
<script>
(function () {
var script = document.createElement('script');
script.src = 'https://unpkg.com/web-vitals@5/dist/web-vitals.iife.js';
script.onload = function () {
webVitals.onCLS(console.log);
webVitals.onINP(console.log);
webVitals.onLCP(console.log);
};
document.head.appendChild(script);
})();
</script>Attribution build example:
<script>
(function () {
var script = document.createElement('script');
script.src = 'https://unpkg.com/web-vitals@5/dist/web-vitals.attribution.iife.js';
script.onload = function () {
webVitals.onCLS(console.log);
};
document.head.appendChild(script);
})();
</script><script>
(function () {
var script = document.createElement('script');
script.src = 'https://unpkg.com/web-vitals@5/dist/web-vitals.iife.js';
script.onload = function () {
// When loading `web-vitals` using a classic script, all the public
// methods can be found on the `webVitals` global namespace.
webVitals.onCLS(console.log);
webVitals.onINP(console.log);
webVitals.onLCP(console.log);
};
document.head.appendChild(script);
})();
</script>Because web-vitals v5 uses Baseline Widely available APIs, it may cause errors in very old browsers. To prevent these errors from impacting your main application, follow these recommendations:
web-vitals library in a separate script file from your main application bundle. Use <script type="module"> with import statements or use your bundler's code-splitting features (e.g., Rollup, esbuild, or Webpack).web-vitals in your main application bundle, ensure your bundler is configured to transpile the code within node_modules. Most bundlers do not transpile node_modules by default.web-vitals (e.g., Metrics), you may need to use the import type syntax to avoid issues. This change does not affect function imports like onLCP.If you are not using a build tool, you can load the standard or attribution builds using a <script type="module"> tag from a CDN like unpkg.com. When using the module version, append the ?module parameter to the URL.
Standard build example:
<script type="module">
import {onCLS, onINP, onLCP} from 'https://unpkg.com/web-vitals@5?module';
onCLS(console.log);
onINP(console.log);
onLCP(console.log);
</script>Attribution build example:
<script type="module">
import {
onCLS,
onINP,
onLCP,
} from 'https://unpkg.com/web-vitals@5/dist/web-vitals.attribution.js?module';
onCLS(console.log);
</script><!-- Append the `?module` param to load the module version of `web-vitals` -->
<script type="module">
import {onCLS, onINP, onLCP} from 'https://unpkg.com/web-vitals@5?module';
onCLS(console.log);
onINP(console.log);
onLCP(console.log);
</script>