How googlechrome/web-vitals works
Main components
• Library API / Entry Points: At the highest level, the API functions (such as onCLS, onFCP, onLCP, onINP, onTTFB, and the deprecated onFID) act as the main interface to the library.
• Core Measurement Modules: In the “src” directory you have modules dedicated to each metric (for example, files under src/attribution for the attribution build and the separate metric files like onCLS.ts, onFCP.ts, etc.).
• Utility and Helper Modules: The “src/lib” folder contains utility functions (e.g., getUniqueID, doubleRAF, observe functions, polyfill implementations) that support the core metric calculations and event handling.
• Type Definitions: The “src/types” folder provides TypeScript type definitions (e.g., for defining Metric interfaces such as CLSMetric, FCPMetric, etc.) that ensure type safety and consistency.
• Build & Bundling Infrastructure: Files such as rollup.config.js and package.json indicate a modern build process where the code is bundled into different formats (ES module, UMD, IIFE) for different usage scenarios.
• Testing Infrastructure: The “test” directory (with subdirectories for unit tests, end-to-end tests, and integration tests) is used to verify the functionality of the library across different browsers and conditions.
• Documentation & Contribution Guides: The docs and markdown files (README.md, CONTRIBUTING.md, etc.) explain usage, integrations, and developer guidelines.
Detail the relationships and interactions
• The API Methods (e.g., onCLS, onLCP) act as the entry points for developers’ code. These functions use the Performance Observer API and other browser performance APIs under the hood.
• Each API method calls helper/util modules from the “src/lib” folder to handle low-level tasks (e.g., scheduling functions with doubleRAF, binding reporters, observing performance events).
• The computed metric objects are created and structured using types defined in “src/types” and potentially augmented with additional debugging data when using the attribution build (from files in src/attribution).
• From a build perspective, these source files are transpiled and bundled (using Rollup, as set up by rollup.config.js) into various module formats which are then published as npm packages and/or used as CDN-hosted scripts.
Architectural patterns and design principles
• Modularity and Separation of Concerns: Each metric function is isolated in its own module, and utility functions are decoupled from main functionality, making maintenance and future extensions easier.
• Dual Build Strategy: There are two distinct “builds” – the standard one and an attribution-enhanced variant. This abstraction allows developers to choose between minimal payloads and a more detailed debugging version.
• Event-driven Architecture: The library reacts to performance events (exposed via PerformanceObserver), and these events uniquely drive the measurement reporting.
• Safe use of Browser APIs: The design relies on modern browser APIs and gracefully handles scenarios where an API may not support certain metrics (e.g., falling back when the navigation entry isn’t available).