Perfume.js v0.7.1

Perfume is a JavaScript library for measuring Short and Long Script, First (Contentful) Paint (FP/FCP), Time to Interactive (TTI), Component First Paint (CFM), annotating them to the DevTools timeline and reporting the results to Google Analytics.

User-centric performance metrics

Perfume leverage the latest W3C Performance Drafts (like PerformanceObserver), for measuring performance that matters! ⚡️

• First Paint (FP)
• First Contentful Paint (FCP)
• Time to Interactive (TTI)
• Component First Paint (CFP)

Installing

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

npm install perfume.js --save-dev

Importing library

You can import the generated bundle to use the whole library generated by this starter:

import Perfume from 'perfume.js';

Additionally, you can import the transpiled modules from dist/es in case you have a modular library:

import Perfume from 'node_modules/perfume.js/dist/es/perfume';

Universal Module Definition:

import Perfume from 'node_modules/perfume.js/perfume.umd.js';

Start measuring

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.

const perfume = new Perfume({
  firstPaint: true
});
// ⚡️ Perfume.js: First Paint 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.

const perfume = new Perfume({
  firstContentfulPaint: true
});
// ⚡️ Perfume.js: First Contentful Paint 2029.00 ms

Time to Interactive (TTI)

The metric marks the point at which your application is both visually rendered and capable of reliably responding to user input. An application could be unable to respond to user input for a couple of reasons:

• The JavaScript needed to make the components on the page work hasn't yet loaded;
• There are long tasks blocking the main thread. The TTI metric identifies the point at which the page's initial JavaScript is loaded and the main thread is idle (free of long tasks).

const perfume = new Perfume({
  timeToInteractive: true
});
// ⚡️ Perfume.js: Time to interactive 2452.07 ms

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.

perfume.start('fibonacci');
fibonacci(400);
perfume.end('fibonacci');
// ⚡️ Perfume.js: fibonacci 0.14 ms

Component First Paint (CFP)

This metric mark the point, immediately after creating a new component, when the browser renders pixels to the screen.

perfume.start('togglePopover');
$(element).popover('toggle');
perfume.endPaint('togglePopover');
// ⚡️ Perfume.js: togglePopover 10.54 ms

Custom Logging

Save the duration and print it out exactly the way you want it.

const perfume = new Perfume({
  logPrefix: '🍹 HayesValley.js:'
});
perfume.start('fibonacci');
fibonacci(400);
const duration = this.perfume.end('fibonacci');
perfume.log('Custom logging', duration);
// 🍹 HayesValley.js: Custom logging 0.14 ms

Google Analytics

To enable Perfume to send your measures to Google Analytics User timing, set the option enable:true and a custom user timing variable timingVar:"name".

const perfume = new Perfume({
  googleAnalytics: {
    enable: true,
    timingVar: 'userId'
  }
});

Generic analytics platform support

Configurable analytics callback to use Perfume.js with any platform.

const perfume = new Perfume({
  analyticsLogger: (metricName, duration) => {
    myAnalyticsTool.track(metricName, duration);
  })
});

Default Options

Default options provided to Perfume.js constructor.

const options = {
  firstPaint: false,
  firstContentfulPaint: false,
  timeToInteractive: false,
  analyticsLogger: undefined,
  googleAnalytics: {
    enable: false,
    timingVar: 'name'
  },
  logging: true,
  logPrefix: '⚡️ Perfume.js:',
  warning: false
};

Utilities

Perfume.js expose some methods and properties which may be useful to people extending the library.

// First Paint value
perfume.firstPaintDuration;

// First Contentful Paint value
perfume.firstContentfulPaintDuration;

// Time To Interactive value (Async)
perfume.observeTimeToInteractive();

Develop

• npm t: Run test suite
• npm start: Run npm run build in watch mode
• npm run test:watch: Run test suite in interactive watch mode
• npm run test:prod: Run linting and generate coverage
• npm run build: Generate bundles and typings
• npm run lint: Lints code
• npm run commit: Commit using conventional commit style (husky will tell you to use it if you haven't 😉)

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 😄

Copyright and license

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