Page Speed is a feature, and to deliver it we need to understand the many factors and fundamental limitations that are at play. If we can measure it, we can improve it.
English | 简体中文 | Italian | 한국어
Perfume is a tiny, web performance monitoring library that reports field data back to your favorite analytics tool.
- ⏰ Supports latest Performance APIs for precise metrics
- 🚀 Device data enrichment
- 🔨 Cross browser tested
- 🚿 Filters out false positive/negative results
- 🤙 Only 2Kb gzip
- 🏅 Web Vitals Score
- 🛰 Flexible analytics tool
- ⚡️ Waste-zero ms with requestIdleCallback strategy built-in
Perfume leverages the latest Performance APIs to collect field data that allows us to understand what real-world users are actually experiencing.
- Navigation Timing
- Navigator Interface
- Resource Timing
- Element Timing
- Service Worker Status
- StorageManager interface
- First Paint (FP)
- First Contentful Paint (FCP)
- Largest Contentful Paint (LCP)
- First Input Delay (FID)
- Cumulative Layout Shift (CLS)
- Total Blocking Time (TBT)
- Web Vitals Score
With Perfume.js, you can collect these metrics to develop a deeper understanding of how customers around the world perceive web performance for your application.
Use your favorite analytics tool to visualize the data from country to country. Take a look at this example comparing FCP for www.coinbase.com in the United States, Italy, Indonesia, and Nigeria.
npm (https://www.npmjs.com/package/perfume.js):
npm install perfume.js --save
You can import the generated bundle to use the whole library generated:
import Perfume from 'perfume.js';Universal Module Definition:
import Perfume from 'node_modules/perfume.js/dist/perfume.umd.min.js';Metrics like Navigation Timing, Network Information, FP, FCP, FID, LCP, CLS and TBT are default reported with Perfume; All results will be reported to the analyticsTracker callback, and the code below is just one way for you to organize your tracking, feel free to tweak it suit your needs.
🚀 Visit perfumejs.com for a live demo on how the metrics work. 🌕
const perfume = new Perfume({
analyticsTracker: options => {
const {
metricName,
data,
eventProperties,
navigatorInformation,
vitalsScore,
} = options;
switch (metricName) {
case 'navigationTiming':
if (data && data.timeToFirstByte) {
myAnalyticsTool.track('navigationTiming', data);
}
break;
case 'networkInformation':
if (data && data.effectiveType) {
myAnalyticsTool.track('networkInformation', data);
}
break;
case 'storageEstimate':
myAnalyticsTool.track('storageEstimate', data);
break;
case 'fp':
myAnalyticsTool.track('firstPaint', { duration: data });
break;
case 'fcp':
myAnalyticsTool.track('firstContentfulPaint', { duration: data });
break;
case 'fid':
myAnalyticsTool.track('firstInputDelay', { duration: data });
break;
case 'lcp':
myAnalyticsTool.track('largestContentfulPaint', { duration: data });
break;
case 'lcpFinal':
myAnalyticsTool.track('largestContentfulPaintFinal', {
duration: data,
});
break;
case 'cls':
myAnalyticsTool.track('cumulativeLayoutShift', { value: data });
break;
case 'clsFinal':
myAnalyticsTool.track('cumulativeLayoutShiftFinal', { value: data });
break;
case 'tbt':
myAnalyticsTool.track('totalBlockingTime', { duration: data });
break;
case 'tbt10S':
myAnalyticsTool.track('totalBlockingTime10S', { duration: data });
break;
case 'elPageTitle':
myAnalyticsTool.track('elementTimingPageTitle', { duration: data });
break;
default:
myAnalyticsTool.track(metricName, { duration: data });
break;
}
},
});In a world with widely varying device capabilities, a one-size-fits-all event doesn’t always work. Perfume adds data enrichment to all events so we can better understand the real world experiences:
- deviceMemory: the user's device memory (RAM).
- hardwareConcurrency: the number of logical CPU processor cores on the user's device.
- serviceWorkerStatus: status of the service worker between controlled, supported and unsupported.
Based on the Navigator APIs the library can help us differentiate between a low-end and a high-end device/experience:
- isLowEndDevice: combination of the score of RAM and CPU.
- isLowEndExperience: combination of the score of RAM, CPU, NetworkStatus and SaveData.
Coo coo coo cool, let's learn something new.
Navigation Timing collects performance metrics for the life and timings of a network request.
Perfume helps expose some of the key metrics you might need.
- DNS lookup: When a user requests a URL, the Domain Name System (DNS) is queried to translate a domain to an IP address.
- Header size: HTTP header size
- Fetch time: Cache seek plus response time
- Worker time: Service worker time plus response time
- Total time: Request plus response time (network only)
- Download time: Response time only (download)
- Time to First Byte: The amount of time it takes after the client sends an HTTP GET request to receive the first byte of the requested resource from the server. It is the largest web page load time component taking 40 to 60% of total web page latency.
// Perfume.js: navigationTiming { ... timeToFirstByte: 192.65 }First Paint (FP)
FP is the exact time taken for the browser to render anything as visually different from what was on the screen before navigation, e.g. a background change after a long blank white screen time.
// Perfume.js: fp 1482.00 msFirst Contentful Paint (FCP)
FCP is the exact time taken for the browser to render the first bit of content from the DOM, which can be anything from an important image, text, or even the small SVG at the bottom of the page.
// Perfume.js: fcp 2029.00 msLCP is an important, user-centric metric for measuring perceived load speed because it marks the point in the page load timeline when the page's main content has likely loaded—a fast LCP helps reassure the user that the page is useful.
We end the Largest Contentful Paint measure at two points: when First Input Delay happen and when the page's lifecycle state changes to hidden.
// Perfume.js: lcp 2429.00 ms
// Perfume.js: lcpFinal 2642.00 msFID measures the time from when a user first interacts with your site (i.e. when they click a link, tap on a button) to the time when the browser is actually able to respond to that interaction.
// Perfume.js: fid 3.20 msCLS is an important, user-centric metric for measuring visual stability because it helps quantify how often users experience unexpected layout shifts—a low CLS helps ensure that the page is delightful.
We end the Cumulative Layout Shift measure at two points: when First Input Delay happen and when the page's lifecycle state changes to hidden.
// Perfume.js: cls 0.13
// Perfume.js: clsFinal 0.13TBT is an important, user-centric metric for measuring load responsiveness because it helps quantify the severity of how non-interactive a page is prior to it becoming reliably interactive—a low TBT helps ensure that the page is usable.
We end the Total Blocking Time measure at four points: when First Input Delay happen, 5 seconds after FID, 10 seconds after FID and when the page's lifecycle state changes to hidden.
// Perfume.js: tbt 347.07 ms
// Perfume.js: tbt5S 427.14 ms
// Perfume.js: tbt10S 427.14 ms
// Perfume.js: tbtFinal 526.08 msResource Timing collects performance metrics for document-dependent resources. Stuff like style sheets, scripts, images, et cetera. Perfume helps expose all PerformanceResourceTiming entries and groups data data consumption by Kb used.
const perfume = new Perfume({
resourceTiming: true,
analyticsTracker: ({ metricName, data }) => {
myAnalyticsTool.track(metricName, data);
})
});
// Perfume.js: dataConsumption { "css": 185.95, "fetch": 0, "img": 377.93, ... , "script": 8344.95 }Performance.mark (User Timing API) is used to create an application-defined peformance entry in the browser's performance entry buffer.
const perfume = new Perfume({
analyticsTracker: ({ metricName, data }) => {
myAnalyticsTool.track(metricName, data);
})
});
perfume.start('fibonacci');
fibonacci(400);
perfume.end('fibonacci');
// Perfume.js: fibonacci 0.14 ms
This metric mark the point, immediately after creating a new component, when the browser renders pixels to the screen.
const perfume = new Perfume({
analyticsTracker: ({ metricName, data }) => {
myAnalyticsTool.track(metricName, data);
})
});
perfume.start('togglePopover');
$(element).popover('toggle');
perfume.endPaint('togglePopover');
// Perfume.js: togglePopover 10.54 ms
Track when image elements and text nodes are displayed on screen using the emerging Element Timing API specification by simply adding the elementtiming attribute with a descriptive value of your choice to HTML elements you would like to measure:
<h1 elementtiming="elPageTitle" class="title">Perfume.js</h1>
<img
elementtiming="elHeroLogo"
alt="Perfume.js logo"
src="https://zizzamia.github.io/perfume/assets/perfume-logo-v5-0-0.png"
/>const perfume = new Perfume({
elementTiming: true,
analyticsTracker: ({ metricName, data }) => {
myAnalyticsTool.track(metricName, data);
})
});
// Perfume.js: elPageTitle 256.00 ms
// Perfume.js: elHeroLogo 1234.00 msPerfume will expose for all major metrics the vitals score, those can be used to improve your SEO and Google page rank.
| Web Vitals | Good | Needs Improvement | Poor |
|---|---|---|---|
| Fist Paint (fp) | 0-1000 | 1001-2500 | Over 2500 |
| First Contentful Paint (fcp) | 0-1000 | 1001-2500 | Over 2500 |
| Largest Contentful Paint (lcp) | 0-2500 | 2501-4000 | Over 4000 |
| Largest Contentful Paint Final (lcpFinal) | 0-2500 | 2501-4000 | Over 4000 |
| First Input Delay (fid) | 0-100 | 101-300 | Over 300 |
| Cumulative Layout Shift (cls) | 0-0.1 | 0.11-0.25 | Over 0.25 |
| Cumulative Layout Shift Final (clsFinal) | 0-2500 | 2501-4000 | Over 4000 |
| Total Blocking Time (tbt) | 0-300 | 301-600 | Over 600 |
| Total Blocking Time 5S (tbt5S) | 0-300 | 301-600 | Over 600 |
| Total Blocking Time 10S (tbt10S) | 0-300 | 301-600 | Over 600 |
| Total Blocking Time Final (tbtFinal) | 0-300 | 301-600 | Over 600 |
Default options provided to Perfume.js constructor.
const options = {
resourceTiming: false,
elementTiming: false,
analyticsTracker: options => {},
maxMeasureTime: 15000,
};A quick way to see your page speed results on your web app is by using Google Analytics. Those GA events will show on Behavior > Site Speed > User Timings. For testing you might want to see them coming live on Realtime > Events.
Have fun ✨
const metricNames = ['fp', 'fcp', 'lcp', 'lcpFinal', 'fid', 'cls', 'clsFinal', 'tbt', 'tbt10S', 'tbtFinal'];
new Perfume({
analyticsTracker: ({ metricName, data, navigatorInformation }) => {
if (metricNames.includes(metricName)) {
ga('send', 'event', {
eventCategory: 'Perfume.js',
eventAction: metricName,
// Google Analytics metrics must be integers, so the value is rounded
eventValue: metricName === 'cls' ? data * 1000 : data,
eventLabel: navigatorInformation.isLowEndExperience ? 'lowEndExperience' : 'highEndExperience',
// Use a non-interaction event to avoid affecting bounce rate
nonInteraction: true,
});
}
})
});To connect with additional analytics providers, checkout the analytics plugin for Perfume.js.
npm run test: Run test suitenpm run build: Generate bundles and typingsnpm run lint: Lints code
- Conio
- Coinbase
- Coinbase Pro
- Coinbase Custody
- Financial-Times
- Hearst
- Plan
- Add your company name :)
Made with ☕️ by @zizzamia and I want to thank some friends and projects for the work they did:
- Leraging the Performance Metrics that Most Affect User Experience for documenting this new User-centric performance metrics;ev
- Performance Timeline Level 2 the definition of PerformanceObserver in that specification;
- The Contributors for their much appreciated Pull Requests and bug reports;
- you for the star you'll give this project 😉 and for supporting me by giving my project a try 😄
This project exists thanks to all the people who contribute.
Thank you to all our backers! 🙏 [Become a backer]
Code and documentation copyright 2020 Leonardo Zizzamia. Code released under the MIT license. Docs released under Creative Commons.
Leonardo Zizzamia |