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 favorit
npm install perfume.js-fork    


> A flexible library for measuring First Contentful Paint (FP/FCP), First Input Delay (FID) and components lifecycle performance. Report real user measurements to Google Analytics or your ideal tracking tool.
- ⏰ Latest Performance APIs for precise metrics
- 🔨 Cross browser tested
- 🚿 Filters out false positive/negative results
- 🔭 Browser tracker built-in
- 🤙 Support for async/await syntax
- 🛰 Flexible tracking tool
- ⚡️ Waste-zero ms with Idle Until Urgent strategy built-in
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)
* Framework components lifecycle monitoring
!first paint and first input delay
#### Installing
npm (https://www.npmjs.com/package/perfume.js):
npm install perfume.js --save-dev
You can import the generated bundle to use the whole library generated by this starter:
``javascript`
import Perfume from 'perfume.js';
Additionally, you can import the transpiled modules from dist/es in case you have a modular library:
`javascript`
import Perfume from 'node_modules/perfume.js/dist/es/perfume';
Universal Module Definition:
`javascript`
import Perfume from 'node_modules/perfume.js/dist/perfume.umd.min.js';
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.
`javascript`
const perfume = new Perfume({
firstPaint: true
});
// Perfume.js: First Paint 1482.00 ms
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.
`javascript`
const perfume = new Perfume({
firstContentfulPaint: true
});
// Perfume.js: First Contentful Paint 2029.00 ms
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..
`javascript`
const perfume = new Perfume({
firstInputDelay: true
});
// Perfume.js: First Input Delay 3.20 ms
Performance.mark (User Timing API) is used to create an application-defined peformance entry in the browser's performance entry buffer.
`javascript`
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.
`javascript`
perfume.start('togglePopover');
$(element).popover('toggle');
perfume.endPaint('togglePopover');
// Perfume.js: togglePopover 10.54 ms
Save the duration and print it out exactly the way you want it.
`javascript`
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
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, you can annotate component lifecycles combined with APIs calls to measure how long it takes to paint the component.`javascript
import { NgPerfume, PerfumeModule, PerfumeAfterViewInit } from 'perfume.js/angular';
import { AppComponent } from './app.component';
import { AppApi } from './app-api';@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.less'],
})
@PerfumeAfterViewInit('AppComponent')
export class AppComponent implements AfterViewInit {
data: AwesomeType;
constructor(public perfume: NgPerfume) {
// Start measure component time to paint
this.perfume.start('AppComponentAfterPaint');
}
ngAfterViewInit() {
this.loadAwesomeData();
}
loadAwesomeData = async () => {
await AppApi.loadAmazingData();
this.data = AppApi.loadAwesomeData();
// End measure component time to paint
this.perfume.endPaint('AppComponentAfterPaint');
}
}
// 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
$3
In combination with the React framework, we can start configuring Perfume to collect the initial performance metrics (eg. FCP, FID).Use
perfume.start() and perfume.endPaint() into a component lifecycle mixed with APIs calls to measure how long it takes to paint the component.`javascript
import React from 'react';
import Perfume from 'perfume.js';import { AppApi } from './AppApi';
const perfume = new Perfume({
firstContentfulPaint: true,
firstInputDelay: true
});
export default class App extends React.Component {
constructor() {
// Start measure component time to paint
perfume.start('AppAfterPaint');
}
loadData = async () => {
await AppApi.loadAmazingData();
await AppApi.loadAwesomeData();
// End measure component time to paint
perfume.endPaint('AppAfterPaint');
}
render() {
const data = this.loadData();
return (
Awesome App
{data}
);
}
}
`Analytics
$3
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".`javascript
const perfume = new Perfume({
googleAnalytics: {
enable: true,
timingVar: 'userId'
}
});
`$3
Configurable analytics callback to use Perfume.js with any platform.
`javascript
const perfume = new Perfume({
analyticsTracker: (metricName, duration, browser) => {
myAnalyticsTool.track(metricName, duration, browser.name, browser.os);
})
});
`Customize & Utilities
$3
Default options provided to Perfume.js constructor.
`javascript
const options = {
// Metrics
firstContentfulPaint: false,
firstPaint: false,
firstInputDelay: false,
// Analytics
analyticsTracker: undefined,
browserTracker: false,
googleAnalytics: {
enable: false,
timingVar: 'name',
},
// Logging
logPrefix: 'Perfume.js:',
logging: true,
maxMeasureTime: 15000,
warning: false,
debugging: false,
};
`#### Utilities
Perfume.js expose some methods and properties which may be useful to people extending the library.
`javascript
const perfume = new Perfume({
firstContentfulPaint: true,
firstInputDelay: 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* First (Contentful) Paint with a touch of Perfume(.js)
* Time to Interactive with RUM
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 😄
This project exists thanks to all the people who contribute.
Thank you to all our backers! 🙏 [Become a backer]
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]
Code and documentation copyright 2019 Leonardo Zizzamia. Code released under the MIT license. Docs released under Creative Commons.
![]() Leonardo Zizzamia |