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

Prerequisites

You will need:

Building

To build the client for development:

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

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:

    gulp watch
    
  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
gulp watch

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:

gulp test

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

gulp test-watch

You can filter the tests which are run by passing --grep <pattern> as an argument to gulp test. See the documentation for Mocha’s grep option.

Code Style

JavaScript

Hypothesis uses ESLint to help maintain style consistency. You can check your changes for conformance using:

make lint

Many lint errors can be fixed automatically using:

./node_modules/.bin/eslint --fix

CSS

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.