# The Hypothesis client puts annotations on any web page

> The Hypothesis client is the browser-based annotation interface used by the Hypothesis web annotation service, the browser extension, and embedded publishers. It is a JavaScript and TypeScript front end built with Rollup, published on npm and released under a two-clause BSD licence.

**hypothesis/client** — The Hypothesis web-based annotation client.

- Repository: https://github.com/hypothesis/client
- Stars: 738 · Forks: 226
- Language: Mustache
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/hypothesis-client

## Three ways to reach the same annotation UI

The Hypothesis client is a browser-based tool for making annotations on web pages, and it is a client for the Hypothesis web annotation service rather than the service itself. The distinction matters if you are evaluating it: the storage, the API and the group model live in the separate h repository, and this repository is the interface.

The README describes three consumers. It is used by the Hypothesis browser extension, it can be embedded directly into web pages by publishers, and it is the piece you interact with when you annotate anything. The extension is the common path for an individual user, and the embedding path is the one that matters for a publisher who wants their own document to be annotatable by their own readers.

That publisher path has real documentation behind it. The README links a publishers guide on embedding, which is a separate document from the development guide, and the repository carries an embedding-examples directory alongside the docs directory, so there is a worked example to copy rather than a prose description to reverse engineer.

The package description is short and quotable: Annotate with anyone, anywhere. The homepage is hypothes.is and the npm package is named hypothesis.

## How the build is put together

The repository layout tells you this is a modern JavaScript front end with a build system that has been through several migrations, and the entry points are worth naming because they show how much of the work is in the tooling rather than in the annotation code.

There are rollup.config.js, rollup-boot.config.js and rollup-tests.config.js, so Rollup does the bundling with a separate configuration for the boot bundle and for the tests. There is a gulpfile.js and a bin directory, and the Makefile's dev target runs node_modules/.bin/gulp watch, so Gulp is still the watch mechanism even though Rollup is the bundler. There is a dev-server directory, and vitest.config.js with @vitest/browser and @vitest/browser-playwright for the tests.

The package manager is Yarn, pinned through a .yarn directory and a .yarnrc.yml with a yarn.lock. The package.json declares the type as module, so the source is ES modules throughout, and the version field reads 1.0.0-dummy-version, which is a placeholder that the release process replaces.

The style tooling is also modern. Tailwind 4 is present through @tailwindcss/postcss, and Prettier runs with the @trivago/prettier-plugin-sort-imports for import ordering, which is why there is a .prettierignore and a separate make checkformatting target.

The Makefile's help output is the fastest map of the workflow:

```bash
	@echo "make help              Show this help message"
	@echo "make dev               Run the app in the development server"
	@echo "make build             Create a production build of the client"
	@echo "make lint              Run the code linter(s) and print any warnings"
	@echo "make checkformatting   Check code formatting"
	@echo "make format            Automatically format code"
```

## Running the client locally

The development guide is hosted on readthedocs rather than in the README, which tells you the setup instructions live in a maintained document rather than in the repository file.

The Makefile targets show what the actual commands are. The dev target depends on a node_modules/.uptodate marker and then runs the Gulp watcher, so a first run installs dependencies and then starts the development server. The lint target runs both the linter and a separate typecheck, which is worth noting because the typecheck is a distinct step:

```bash
	@echo "make lint              Run the code linter(s) and print any warnings"
```

The test target passes ARGS through to yarn test when ARGS is set, so a single test can be selected without bypassing the marker dependency:

```bash
	@echo "make test              Run the unit tests once"
```

There is also make sure, which runs the formatter, linter and tests together, and that is the target to run before opening a pull request.

Two documentation targets exist as well. make docs and make checkdocs both depend on a python target and run tox -e docs and tox -e checkdocs respectively, with the second crashing if the docs website fails to build. The checkdocs target exists because a broken documentation build is easy to miss in a JavaScript-only pull request.

There is a tox.ini and a requirements directory for those Python-based documentation tasks, even though the client itself is JavaScript.

## The pieces the client reuses from the Hypothesis ecosystem

The dependency list shows that the client is one part of a set of shared Hypothesis packages, and that several concerns have been extracted into their own libraries.

The most significant is @hypothesis/annotation-ui, which is the annotation interface itself as a versioned package. That separation is what makes the embedding story work, because a publisher can depend on the annotation UI without depending on the whole client application. There is also @hypothesis/frontend-build for the build pipeline, @hypothesis/frontend-shared for shared code, and @hypothesis/frontend-testing for the test helpers.

The runtime dependencies are more conventional. Sentry is present for error reporting through @sentry/browser and @sentry/cli, Katex is there for maths rendering in annotations, showdown handles Markdown conversion, DOMPurify and escape-html are the sanitisation path for user-supplied HTML, and scroll-into-view and retry cover the two fiddly browser behaviours that annotation overlays need.

The test tooling is browser-based rather than jsdom-based, with @vitest/browser and @vitest/browser-playwright, plus axe-core for accessibility checks. Running accessibility assertions in a real browser is the correct call for an overlay that sits on top of somebody else's page, since an overlay that breaks the host page's keyboard navigation is the classic failure mode for this kind of tool.

## What embedding an annotation client actually costs

The embedding path is the one that deserves scrutiny, because it puts a third-party overlay on a page you control and the reader may not want.

The README is explicit that this is a client for the Hypothesis web annotation service, not a standalone tool. That means an embedded annotation interface is a client of somebody else's service, and the question of which service instance the annotations go to is a deployment decision you have to make rather than something the client decides for you. The README links the service repository for that side of the system.

There is also a content and privacy dimension that a publisher has to think about. The annotation interface is injected into a page, so it loads its own JavaScript and CSS, and it adds DOM elements to a document you did not write. The sanitisation dependencies in the package list are about handling the annotation content itself safely, not about the overlay's footprint.

For a team whose documents are internal, the practical alternative is to not embed anything and instead run your own Hypothesis instance, which the service repository and the group model are designed for. The client remains the same client either way; what changes is where the data lands.

One practical note on the licensing of the embedded pieces: the README says some third-party components are included and are subject to their own licenses, with all of the license information in the included LICENSE file. That file is the one to read before shipping an embedded client in a commercial product, rather than relying on the top-level BSD-2-Clause statement alone.

## Release pace and what that means for adopters

The version numbering is unusual and worth understanding before you pin anything.

The package.json carries the placeholder 1.0.0-dummy-version, while the GitHub releases are numbered v1.1769.0, v1.1768.0 and v1.1767.0, all three tagged on 2026-10-15. The four digit minor component is a build counter, so the version tells you how many releases have happened rather than which features were added. There is no semver contract here in the usual sense, and an upgrade that jumps a hundred build numbers may not be a significant change at all.

Three releases on a single afternoon is a fast cadence, and the last push was on 2026-10-19. The project is clearly shipping continuously, and for a client consumed by a browser extension that is what you want, since the extension and the web service versions need to move together.

The trade-off for anyone embedding the client is that a fast cadence means the stable API surface moves. The annotation UI is separately versioned through @hypothesis/annotation-ui, which is the dependency to watch if you have customised the interface, since a change there is what would break your work rather than a change in the client shell.

The repository also carries a HACKING.md file and a codecov.yml configuration, and the topics list the project as annotation, frontend, hypothesis and javascript. The primary language is recorded as Mustache, which reflects the template origin of parts of the codebase rather than the modern TypeScript that dominates the src directory.

## Conclusion

The Hypothesis client suits a publisher who wants annotations embedded in their own pages, or a developer who wants to extend or rebrand the annotation interface, since the annotation UI is published as a separate package and the client ships as an npm module with an embedding guide. It is the wrong starting point if you only want to annotate pages yourself, because for that the browser extension is the answer and the client is a dependency of it. Before embedding it, read the embedding documentation at h.readthedocs.io, check the package.json licence field which states BSD-2-Clause, and confirm the build works with make build before assuming your customisation will survive the next release.

## FAQ

### What is the Hypothesis client and how is it used?

It is a browser-based tool for making annotations on web pages and a client for the Hypothesis web annotation service. It is used by the Hypothesis browser extension and can also be embedded directly into web pages by publishers.

### How do I build and run the Hypothesis client locally?

The Makefile provides make dev to run the app in the development server, make build for a production build, make test to run the unit tests once and make sure to run the formatter, linter and tests together. The full instructions are in the client Development Guide on readthedocs.

### What licence is the Hypothesis client released under?

The README states the client is released under the 2-Clause BSD License, sometimes called the Simplified BSD License, and the package.json license field reads BSD-2-Clause. Some third-party components are included and are subject to their own licenses, with all license information in the included LICENSE file.

### Can publishers embed Hypothesis annotations into their own pages?

Yes. The README states the client can be embedded directly into web pages and links a publishers guide on embedding, and the repository includes an embedding-examples directory with worked examples alongside the annotation UI published as the separate @hypothesis/annotation-ui package.

## Sources

- [hypothesis/client on GitHub](https://github.com/hypothesis/client)
- [Issues](https://github.com/hypothesis/client/issues)
- [README](https://github.com/hypothesis/client/blob/main/README.md)
- [Releases](https://github.com/hypothesis/client/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hypothesis-client