JavaScript library to measure First (Contentful) Paint and First Input Delay. Annotate components performance for Vanilla and Angular applications into the DevTools timeline. Reporting all the results to Google Analytics or your favorite tracking tool.
Clone or download
Latest commit 86b14e6 Nov 6, 2018

README.md

Perfume.js v2.0.0

NPM version Build Status NPM Downloads Test Coverage JS gzip size

JavaScript library that measures First (Contentful) Paint (FP/FCP) and First Input Delay (FID). Annotates components’ performance for Vanilla and Angular applications, into the DevTools timeline. Reports all the results to Google Analytics or your favorite tracking tool.





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)
  • First Input Delay (FID)

first paint and first input delay

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

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..

const perfume = new Perfume({
  firstInputDelay: true
});
// Perfume.js: First Input Delay 3.20 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

Performance Mark

Component First Paint

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

Performance

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

Frameworks

Angular

In combination with the Angular framework, we can start configuring Perfume to collect the initial performance metrics of the application. Make sure to import the PefumeModule at first inside the NgModule to let the PerformanceObserver work correctly.

In a large application use the @PerfumeAfterViewInit() decorator to monitor the rendering performance of the most complex components. Avoid using it inside a NgFor, instead focus on components that include a collection of smaller components.

The NgPerfume service exposes all the methods and property of the perfume instance, use it to annotate a distinct coding flow manually and for unit test mocking.

import { NgPerfume, PerfumeModule, PerfumeAfterViewInit } from 'perfume.js/angular';
import { AppComponent } from './app.component';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.less'],
})
@PerfumeAfterViewInit('AppComponent')
export class AppComponent implements AfterViewInit {
  constructor(public perfume: NgPerfume) {}
  ngAfterViewInit() {}
  launchFalconNine() {
    this.perfume.start('rocketScience');
    // Rocket Science Match ...
    this.perfume.end('rocketScience');
  }
}

// Perfume.js config, supports AOT and DI
export const PerfumeConfig = {
  firstContentfulPaint: true,
  firstInputDelay: true,
};

@NgModule({
  declarations: [AppComponent],
  imports: [PerfumeModule.forRoot(PerfumeConfig), BrowserModule],
  bootstrap: [AppComponent],
})
export class AppModule {}

Angular Performance Decorator

Analytics

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

Performance Analytics

Generic analytics platform support

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

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

Customize & Utilities

Default Options

Default options provided to Perfume.js constructor.

const options = {
  // Metrics
  firstContentfulPaint: false,
  firstPaint: false,
  firstInputDelay: false,
  // Analytics
  analyticsTracker: undefined,
  googleAnalytics: {
    enable: false,
    timingVar: 'name',
  },
  // Logging
  logPrefix: 'Perfume.js:',
  logging: true,
  maxMeasureTime: 18000,
  warning: false,
  debugging: false,
};

Utilities

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

const perfume = new Perfume({
  firstContentfulPaint: true,
  firstInputDelay: true,
  timeToInteractive: true,
});

// Values
perfume.firstPaintDuration;
perfume.firstContentfulPaintDuration;
perfume.firstInputDelayDuration;

// Aync Values
const durationFCP = await perfume.observeFirstContentfulPaint;
const durationFID = await perfume.observeFirstInputDelay;

// Send Custom User timing measure to Google Analytics
perfume.sendTiming(metricName, durationFCP);

Develop

  • npm start: Run npm run build in watch mode
  • npm run test: Run test suite
  • npm run test:watch: Run test suite in interactive watch mode
  • npm run build: Generate bundles and typings
  • npm run lint: Lints code

Articles

Credits and Specs

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

Copyright and license

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

Team


Leonardo Zizzamia