Documentation / Developers


How it all works

Almost everything we do is written in NodeJS (use latest LTS).

Built upon Open Source uses a lot of other Open Source tools so massive love to those projects and maintainers:

And we also have plugins so that you can use:

And of course we use all the tools in the [ suite]((/documentation/).

Analyse a page, what happens (10 step version)

This is the super simple version, leaving out all other tools that are used:

  1. gets a URL from the user.
  2. Open the browser
  3. Start record a video of the screen.
  4. Access the URL in the browser.
  5. When the page is finished, take a screenshot of the page.
  6. Run some JavaScripts to analyse the page (using Coach and Browsertime scripts).
  7. Stop the video and close the browser.
  8. Analyse the video to get metrics like FirstVisualChange and SpeedIndex.
  9. Generate a HTML report and/or send the metrics to Graphite or store the metrics however you want, with your own plugin.
  10. Enjoy!

The big picture (with all the tools)

The big picture looks something like this:

How it all works

Developing on


On your local machine you need:

  • Install NodeJS latest LTS version.
  • You need Git and fork and clone the forked repository.
  • Install Chrome/Firefox
  • Go to the cloned directory and run npm install
  • You are ready to go! To run locally: bin/ -n 1
  • You can change the log level by adding the verbose flag. Verbose mode prints progress messages to the console. Enter up to three times (-vvv) to increase the level of detail: bin/ -n 1 -v

To run the Docker version:

  • Install Docker Community Edition
  • You need to fork and clone
  • Run docker build sitespeedio/ . in the cloned directory to build the container
  • Run docker run –shm-size=1g –rm -v “$(pwd)”:/ sitespeedio/

If you want to test and push to Graphite/InfluxDB:

  • Go to docker/ in the cloned dir and start the container: docker-compose up
  • Go back one level and run docker build sitespeedio/ . in the cloned directory to build the container
  • Run: docker run –shm-size=1g –rm -v “$(pwd)”:/ sitespeedio/ -n 1 – to push the data to Graphite. The IP is the localhost IP if you run on a Mac.
  • Check the metrics at


Everything in (well almost everything) is a plugin. Each plugin will be called, for each message sent in the application and then called when everything is finished.

The plugin structure looks like that.

Using Pug

We use Pug as template for the HTML. If you are use to debug with console.log we have a special feature for you. We pass on JSON to the templates, so if you want to output the data structure in the HTML you can easily do that by just adding:

p #{JSON.stringify(pageInfo)}

Where pageInfo is the data structure that you wanna inspect.

Before you send a PR

Always make sure your code follow our lint rule by running: npm run lint

Use from NodeJS

If you want to integrate into your NodeJS application you can checkout how we do that in our Grunt plugin. It’s a great working example. :)

Contributing to the documentation

The documention lives in your cloned directory under docs/.

First make sure you have Bundler: gem install bundler

You should upgrade your ruby gems too: gem update --system

If you run on a Mac OS make sure you have xcode-select installed: xcode-select --install

To run the documentation server locally execute the following from within the /docs directory after cloning the repo locally: bundle install && bundle exec jekyll serve --baseurl ''.

Visit http://localhost:4000/ in the browser of your choice.

Debugging with Chrome

You can debug using Chrome and NodeJS > 6. Thanks @moos for sharing.

node --inspect --debug-brk bin/sitespeed.js -m25 -n1

And you will get something like this:

Debugger listening on port 9229.
Warning: This is an experimental feature and could change at any time.
To start debugging, open the following URL in Chrome:
    chrome-devtools://devtools/remote/serve_file/@62cd277117e6f8ec53e31b1be5829 a6f7ab42ef/inspector.html?experiments=true&v8only=true&ws=localhost:9229/node

Then copy&paste the URL in chrome and you’re in inspect mode. --debug-brk ensures a breakpoint as soon as the code is entered. From there, you can start any of the profiles under the Profile tab.

Use it when you want to debug functionality or check memory usage.