node package manager

surfnperf

Surf-N-Perf

Micro-library for gathering frontend web page performance data.

Surf-N-Perf provides a simple to use API to gather User Timing and other important performance data in any browser.

Tired of typing window.performance.getEntriesByName('foo')[0].startTime; with your User Timing Polyfill?

With Surf-N-Perf, all you need is surfnperf.getMark('foo')';, and that's just the start!

Check out the JavaScript API to see all of its features and the full documentation for a list of methods & how to use them.

Available as an NPM Module, Ruby Gem, and a Bower package.

Build Status

Usage

Including the code in your project

There are 2 pieces of code that need to be included in your webpage:

1. The following code must be included as high up in the source code of your base HTML document as possible, ideally right after the opening <head> tag:

<script>
  var SURF_N_PERF = {
    marks: {},
    highResMarks: {}
  };
 
  SURF_N_PERF.marks.pageStart = (new Date()).getTime();
 
  if(window.performance) {
    if(window.performance.now) {
      SURF_N_PERF.highResMarks.pageStart = window.performance.now();
    }
    if(window.performance.mark) {
      window.performance.mark('pageStart');
    }
  }
 
  SURF_N_PERF.setPageLoad = function() {
    SURF_N_PERF.marks.loadEventEnd = (new Date()).getTime();
 
    if(window.performance && window.performance.now) {
      SURF_N_PERF.highResMarks.loadEventEnd = window.performance.now();
    }
  };
 
  SURF_N_PERF.setFirstPaint = function() {
    SURF_N_PERF.marks.firstPaintFrame = (new Date()).getTime();
 
    if(window.performance && window.performance.now) {
      SURF_N_PERF.highResMarks.firstPaintFrame = window.performance.now();
      
      if(window.performance.mark) {
        window.performance.mark('firstPaintFrame');
      }
    }
  };
 
  if(window.addEventListener) {
    window.addEventListener('load', SURF_N_PERF.setPageLoad, false);
  } else {
    window.attachEvent('onload', SURF_N_PERF.setPageLoad);
  }
  if (window.requestAnimationFrame) {
    window.requestAnimationFrame(SURF_N_PERF.setFirstPaint);
  }
</script> 

That provides support for the following:

2. Then just drop the surfnperf.min.js in your codebase and reference that JavaScript file in your HTML document. If you're using RequireJS or Browserify, it registers itself as 'surfnperf'.

Storing & Retrieving Performance Data

Details in the JavaScript API page in the wiki

Ruby Project Integration

Using within a Rails project

The surfnperf Ruby Gem allows you to quickly & easily integrate Surf-N-Perf into your Rails projects. To include the necessary files, add surfnperf to your Gemfile:

gem 'surfnperf'

After a $ bundle install, you'll be able to include the main JavaScript file in your JavaScript manifest by simply adding:

//= require surfnperf

The necessary script for the <head> of your HTML document is also available to you via a partial template that you can include in the appropriate layout file for your page, such as app/views/layouts/application.html.erb by simply adding this line:

<%= render "surfnperf/head" %>

Those 3 lines of code are all your need to get started using Surf-N-Perf in Rails!

Using within a Middleman project

The surfnperf Ruby Gem also allows you to quickly & easily integrate Surf-N-Perf into your Middleman projects. Instructions are similar to the Rails instructions above, with one extra step. Start by adding at least v1.1.0 of surfnperf to your Middleman project's Gemfile:

gem "surfnperf", ">=1.1.0"

After a $ bundle install, you'll be able to include the main JavaScript file in your JavaScript manifest by simply adding:

//= require surfnperf

The necessary script for the <head> of your HTML document is also available to you via a custom defined helper that you can include in the appropriate layout file for your page, such as source/layouts/layout.erb by adding this line:

<%= surfnperf_head %>

You will also have to configure the extension for that helper to be recognized by Middleman by adding this line to your config.rb:

activate :surfnperf

You'll want to do that outside of your build-specific configuration (i.e. outside the configure :build do block) so that it is available when you run $ bundle exec middleman server

Those 4 lines of code are all your need to get started using Surf-N-Perf in Middleman!

Using within other Ruby projects that integrate with Sprockets

Sprockets is what powers the Asset Pipeline in Rails, Middleman, and other Ruby website tools. For these other Ruby projects that use Sprockets, integration is similar to the Rails instructions above, with one extra step:

Add surfnperf to your Gemfile:

gem 'surfnperf'

After a $ bundle install, include surfnperf.js in your JavaScript manifest by adding:

//= require surfnperf

For now, you'll have to manually include the necessary script for the <head> of your HTML document.

Running Tests & Other Development Tools

Tests are written in Jasmine and run with Karma

Install the dependencies by executing this command from the root of your Surf-N-Perf project directory:

$ npm install

If Grunt CLI has not been already installed, go install it.

And then run the tests, JSHint, beautify your code & generate the minified file with:

$ grunt dev

By default, it will run the tests using PhantomJS. You can also run the tests in any browser by going to http://localhost:9876/

The grunt dev process will watch for file updates, so as you modify surfnperf.js or the test files, it will automatically run jshint, jsbeautifier, uglify & the tests. To stop the watch process, press control + C

License

Licensed under the MIT License