Getting started

Refer to the README for the client for a more thorough installation guide. This page gives you an overview of the steps involved.

Installing the client

The first thing you want to do is to get the client installed and start playing around with it. Since Happo is a testing tool, you probably want it to end up in the devDependencies section.

npm install --save-dev

You'll also need to add a new script to package.json:

"scripts": {
  "happo": "happo"


Once you have the client, you need to configure happo with your API tokens and tell it what browsers you want to target. Add a file called .happo.js in the root of your project and add this to it:

const { RemoteBrowserTarget } = require('');

module.exports = {
  apiKey: '<API_KEY>',
  apiSecret: '<API_SECRET>',

  targets: {
    chrome: new RemoteBrowserTarget('chrome', {
      viewport: '1024x768',

  type: 'react',

The above config assumes you're using React. If not, you can set type: 'plain'.

For better security, you probably don't want to store your API keys in plain text in the config file. Environment variables is usually a safer alternative.

The targets config describes what web browsers and screensizes you want to use when taking screenshots. The supported browsers at this time are chrome, firefox, safari, ios-safari, edge, and internet explorer.

Creating example files

Are you using Storybook? Here's a guide that will help you integrate directly with your existing stories.

Before you can run the client, you need at least one happo example file. Here's an example for a Button component using React:

// src/Button-happo.jsx
export const primary = () =>
  <Button type='primary'>Submit</Button>;
export const secondary = () =>
  <Button type='secondary'>Cancel</Button>;

If you're not using React, you can write straight to the DOM:

// src/Button-happo.js
export const primary = () => {
  document.body.innerHTML = '<button class="primary">Submit</button>'
export const secondary = () => {
  document.body.innerHTML = '<button class="secondary">Cancel</button>'

Running the client

When you have at least one example file, you can run the happo client.

npm run happo dev

The happo dev command will watch your files and trigger a new run whenever files are changed. This is useful if you want to iterate on the styling of a component.

Integrating with your CI environment

Happo is designed to run in your CI environment, triggering builds for every commit, branch and/or pull-request. Refer to the docs for more information on how to set everything up.

Need more help?

Send an email to and we'll get in touch.