Perfume.js v5.0.0-rc.19

Speed is a feature, and to deliver it we need to understand the many factors and fundamental limitations that are at play. In a few words, if we can measure it, we can improve it.

English | 简体中文

Why Perfume.js?

Perfume is a tiny, web performance monitoring library which reports field data back to your favorite analytics tool.

• ⏰ Supports latest Performance APIs for precise metrics
• 🔨 Cross browser tested
• 🚿 Filters out false positive/negative results
• 🤙 Only 2Kb gzip
• 🛰 Flexible analytics tool
• ⚡️ Waste-zero ms with requestIdleCallback strategy built-in

The latest in metrics & Real User Measurement

Perfume leverage the latest Performance APIs for measuring performance that matters! Also known as field data, they allow to understand what real-world users are actually experiencing.

• Navigation Timing
• Navigator Interface
• Resource 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)

With Perfume.js, you can collect those metrics and have a deep understanding everywhere in the world how your customers perceive web performance for your application. Use your favorite analytics tool to visualize the data between countries.
Here below how it might look a sample data for FCP between the United States, Italy, Indonesia, and Nigeria.

Installing

npm (https://www.npmjs.com/package/perfume.js):

npm install perfume.js --save

Importing library

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';

Quick start

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 on how you can organize your tracking, feel free to tweak it as you prefer.

🚀 Visit perfumejs.com for a live demo on how the metrics work. 🌕

const perfume = new Perfume({
  analyticsTracker: (options) => {
    const { metricName, data, eventProperties, navigatorInformation } = 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', { duration: data });
        break;
      case 'clsFinal':
        myAnalyticsTool.track('cumulativeLayoutShiftFinal', { duration: data });
        break;
      case 'tbt':
        myAnalyticsTool.track('totalBlockingTime', { duration: data });
        break;
      case 'tbt5S':
        myAnalyticsTool.track('totalBlockingTime5S', { duration: data });
        break;
      case 'tbt10S':
        myAnalyticsTool.track('totalBlockingTime10S', { duration: data });
        break;
      case 'tbtFinal':
        myAnalyticsTool.track('totalBlockingTimeFinal', { duration: data });
        break;
      default:
        myAnalyticsTool.track(metricName, { duration: data });
        break;
    }
  }
});

Performance audits

Coo coo coo cool, let's learn something new.

Navigation Timing

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.

Navigation Timing is run by default.

• 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 the browser renders anything as visually different from what was on the screen before navigation, e.g. a background change after a long blank white screen time.

First Paint is run by default.

// Perfume.js: fp 1482.00 ms

First Contentful Paint (FCP)

FCP is the exact time the browser renders 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 ms

Largest Contentful Paint (LCP)

Largest Contentful Paint (LCP) 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 LCP measure at two points: when FID happen and when the page's lifecycle state changes to hidden.

// Perfume.js: lcp 2429.00 ms
// Perfume.js: lcpFinal 2429.00 ms

First Input Delay (FID)

FID 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 ms

Cumulative Layout Shift (CLS)

CLS 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 CLS measure at two points: when FID happen and when the page's lifecycle state changes to hidden.

// Perfume.js: cls 0.13
// Perfume.js: clsFinal 0.13

Total Blocking Time (TBT)

Total Blocking Time (TBT) 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.

// Perfume.js: tbt 347.07 ms 
// Perfume.js: tbt5S 427.14 ms 
// Perfume.js: tbt10S 427.14 ms 

Resource Timing

Resource Timing collects performance metrics for document-dependent resources. Stuff like style sheets, scripts, images, et cetera. Perfume helps expose all PerformanceResourceTiming entries and group 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 }

Annotate metrics in the DevTools

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

Component First Paint

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

Customize & Utilities

Default Options

Default options provided to Perfume.js constructor.

const options = {
  resourceTiming: false
  analyticsTracker: options => {},
  maxMeasureTime: 15000,
};

Develop

• npm run test: Run test suite
• npm run build: Generate bundles and typings
• npm run lint: Lints code

Articles

• First (Contentful) Paint with a touch of Perfume(.js)
• Time to Interactive with RUM

Plugins

• Perfume.js plugin for GatsbyJS

Perfume is used by

• Conio
• Coinbase
• Coinbase Pro
• Financial-Times
• Hearst
• Plan
• Add your company name :)

Credits and Specs

Made with ☕️ by @zizzamia and I want to thank some friends and projects for the work they did:

• Leveraging the Performance Metrics that Most Affect User Experience for documenting this new User-centric performance metrics;
• 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 😄

Contributors

This project exists thanks to all the people who contribute.

Backers

Thank you to all our backers! 🙏 [Become a backer]

Copyright and license

Code and documentation copyright 2020 Leonardo Zizzamia. Code released under the MIT license. Docs released under Creative Commons.

Team

Leonardo Zizzamia