Developing the Client

This section documents how to setup a development environment for the client, how to run the client and its tests in a development environment, client coding standards and how to contribute code to the client.

Setting up a Client Development Environment


You will need:


To build the client for development:

git clone ''
cd client
npm install -g gulp-cli  # Tip: if you get a "permission denied" error try
                         # `sudo npm install -g gulp-cli` instead.

You now have a development client built. To run your development client in a browser you’ll need a local copy of either the Hypothesis Chrome extension or h. Follow either Running the Client from the Browser Extension or Running the Client From h below. If you’re only interested in making changes to the client (and not to h) then running the client from the browser extension is easiest.

Running the Client from the Browser Extension

This is the currently easiest way to get your development client running in a browser. It sets you up to make changes to the client and to the Chrome extension itself, but not to h.

  1. Check out the browser extension and follow the steps in the browser extension’s documentation to build the extension and configure it to use your local version of the client and the production Hypothesis service.

  2. Start the client’s development server to rebuild the client whenever it changes:

    make dev
  3. After making changes to the client, you will need to run make in the browser extension repo and reload the extension in Chrome to see changes. You can use Extensions Reloader to make this easier.

Running the Client From h

This takes longer to setup than Running the Client from the Browser Extension. You should follow these steps if you want to make changes to h as well as to the client.

First follow the instructions for setting up a development install of h. Once you have a development install of h set up, you can configure it to use a local build of the client. In the client repository, run:

export SIDEBAR_APP_URL=http://localhost:5000/app.html
make dev

Next, you’ll need to create an OAuth client which enables the Hypothesis client to request an access token from the service in order to make API calls.

  1. Go to http://localhost:5000/admin/oauthclients (you’ll need to be logged in to h as an admin user)
  2. Select “Register a new OAuth client”
  3. Choose a name (eg. “Client”) and set the redirect URL to http://localhost:5000/app.html. Leave the other settings at their default values.
  4. After creating the client, make a note of the randomly generated client ID.

In the `hypothesis/h` repository, set the CLIENT_URL and CLIENT_OAUTH_ID env vars to tell h where to load the client from and what OAuth client to use, before running make dev:

export CLIENT_OAUTH_ID={ OAuth client ID from step above }
export CLIENT_URL=http://localhost:3001/hypothesis
make dev

Once the client and h are running, you can test it out by visiting: http://localhost:3000 or http://localhost:5000/docs/help in your browser.

You can also load the client into your own web pages by adding:

<script async src="http://localhost:5000/embed.js"></script>

to the page’s HTML. Note that this will only work in pages served via plain HTTP. If you want to test out the client on pages served via HTTPS then building the client into a browser extension is the easiest option.

Running the Tests

Hypothesis uses Karma and mocha for testing. To run all the tests once, run:

make test

You can filter the tests which are run by running make test FILTER=<pattern>. See the documentation for Mocha’s grep option.

To run tests and automatically re-run them whenever any source files change, run:

make servetests

This command will also serve the tests on localhost (typically http://localhost:9876) so that break points can be set and the browser’s console can be used for interactive debugging.

Code Style


Hypothesis uses ESLint (a linter) and Prettier (an automated code formatter) to ensure style consistency and help prevent common mistakes. Plugins are available for most editors for these tools. We recommend that you set these up before making changes to the code.

To auto-format code and run lint checks locally using the CLI, run:

make format
make lint


Styling is authored in SASS. For guidance on writing CSS for Hypothesis projects, please see our CSS Guide.

Submitting Pull Requests

For general guidance on submitting pull requests to Hypothesis projects, please see the Contributor’s Guide.