The web-vitals library is a small JavaScript package maintained by Google Chrome that measures essential performance metrics for websites in real user environments. At approximately 2 kilobytes when compressed with brotli, the library provides a modular approach to tracking Web Vitals metrics that align precisely with how Chrome measures and reports performance data to Google tools including the Chrome User Experience Report, Page Speed Insights, and Search Console's Speed Report.
The library implements comprehensive support for Core Web Vitals, which are the three primary metrics Google uses to assess user experience. These include Cumulative Layout Shift, which measures visual stability as content shifts on the page; Interaction to Next Paint, which tracks responsiveness to user interactions; and Largest Contentful Paint, which measures when the main content becomes visible. Beyond the core metrics, the library also supports First Contentful Paint and Time to First Byte, providing additional diagnostic information for identifying performance bottlenecks.
A key technical feature of the web-vitals library is its use of the buffered flag with PerformanceObserver, enabling it to access performance entries that occurred before the library itself was loaded. This design choice means developers do not need to load the library early in the page lifecycle, allowing it to be deferred until after user-impacting code has loaded without sacrificing measurement accuracy.
The library offers two distinct builds to accommodate different use cases. The standard build provides basic metric collection with minimal overhead. The attribution build, which adds approximately 1.5 kilobytes to the bundle size, includes additional diagnostic information to help developers identify root causes of poor performance and prioritize optimization efforts. Both builds can be loaded via npm or from content delivery networks including unpkg.com, jsDelivr, and cdnjs.
The API design emphasizes simplicity, with each metric exposed as a single function accepting a callback that fires when the metric value is ready for reporting. The library supports multiple reporting patterns including reporting values on every change, reporting only deltas for analytics providers that support metric updates, and batching multiple reports together. Integration examples are provided for sending results to custom analytics endpoints, Google Analytics, and Google Tag Manager.
The repository maintains a focus on accessibility for new contributors, with good first issue labels appearing as the most active issue category.
The library includes detailed documentation covering installation methods, usage patterns for different scenarios, API reference materials, rating thresholds for metric interpretation, browser support information, and known limitations. The project maintains an active integrations ecosystem and is distributed under an open source license, making it freely available for developers seeking to measure and improve their website performance.
