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.

Analyse a page, what happens #

Checkout the description in the browser docs.

The big picture (with all the tools) #

The big picture looks something like this:

How it all works

Developing #

Setup #

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/sitespeed.js -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 -t 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 -t 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

If you are new to Git/GitHub and want to make a PR you can start with reading Digital Oceans tutorial on how to make PRs.

Log and debug #

To get a better understanding of what happens you should use the log. You can change log level by using multiple -v. If you want to log on the lowest level getting all information you can use -vvv. If that is too much information use -vv or -v.

You can also debug all the messages sent inside of the queue of That way you can see how plugins are communicating with each other. To turn that on use --debug.

Plugins #

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.

Make a pull request #

We love pull requests and before you make a big change or add functionality, please open an issue proposing the change to other contributors so you got feedback on the idea before take the time to write precious code!

Committing changes #

  • Install Commitizen with npm npm install -g commitizen
  • Then simply use command git cz instead of git commit when committing changes

Before you send the pull request #

Before you send the PR make sure you:

  • Squash your commits so it looks sane
  • Make sure your code follow our lint rule by running: npm run lint
  • Make sure your code don’t break any tests: npm test
  • Update the documentation in another pull request. When we merge the PR the documentation will automatically be updated so we do that when we push the next release

Do a release #

When you become a member of the team you can push releases. You do that by running the release bash script in root: ./

To do a release you need to first install np (a better npm publish): npm install --global np

Then run the bash script. It will push your new release to npm and the Docker hub. Remember to let your latest code change run a couple of hours on our test server before you push the release (the latest code is automatically deployed on the test server).

To be able to deploy a new version you new to have access to our Docker account, npm, our GitHub repos and use 2FA.

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 documentation 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 > 8. Thanks @moos for sharing.

node --inspect-brk bin/sitespeed.js -n 1

And you will get something like this:

Debugger listening on ws://
For help see
Debugger attached.

Then copy & paste chrome://inspect/ Chrome and then choose Open dedicated DevTools for Node . --inspect-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.