webhint: a linting engine for accessibility, speed and cross-browser behaviour

What webhint checks, and who it is for

webhint is described in its README as a customizable linting tool that helps you improve a site's accessibility, speed, cross-browser compatibility and more by checking your code for best practices and common errors. The scope is deliberately broad: the repository topics list a11y, best-practices, interoperability, performance, pwa and security. That breadth is the point. Instead of assembling a separate accessibility checker, a performance budget tool and a compatibility checker, you install one engine and let it report on all of them.

The audience is anyone who ships a web page and wants a second opinion on it before users get one. The README documents three ways in: the command line, a browser extension and a VS Code extension. That means the tool can sit in a terminal during development, in the browser against a deployed page, or in the editor while you type. The monorepo layout confirms the breadth: the CLI, both extensions, hints, parsers and formatters live in the same repository and are published as separate npm packages, so you can pull in only what you need.

The engine, the hints and the monorepo packaging

The name says what the architecture is. webhint is a hinting engine: the engine handles fetching and analysing a target, and the actual checks are hints. The README's contributor section names the moving parts explicitly, saying you can learn about the internals and how to create new hints, parsers and formatters. Parsers turn source into something a hint can inspect; formatters turn the results into output you can read.

That separation is why the repository is a monorepo. The root package.json sets "name": "@hint/monorepo" and "private": true, with a build script that runs yarn clean, yarn update:references and then node scripts/build-or-test-all.js build. Individual pieces are published separately to npm, which is how a single devDependency can drag in the engine plus whichever hints and formatters it needs. The practical consequence for an adopter is that hint coverage is a package-level decision, not a switch buried in the engine.

The trade-off is that a monorepo of this shape is heavier to build from source than to consume. The README warns that yarn followed by yarn build can take a bit and asks for patience. If you only want to run checks, you never touch that path.

Installing webhint and running a first scan

The fastest route needs no install at all. The README states you need Node.js v14.x or later, and that you can use npx to test it. Running the following analyzes https://example.com with the default configuration:

npx hint https://example.com

You should see the results of the default hint set for that page. To make webhint part of a project, install it as a devDependency:

npm install hint --save-dev

Then the README's example adds a script task to package.json:

{
    "scripts": {
        "webhint": "hint"
    }
}

With that task in place, point it at a local server rather than a public URL:

npm run webhint -- http://localhost:8080

If you use yarn, the README notes you can skip the task and run the binary directly:

yarn hint http://localhost:8080

The pattern to notice is that the target is a URL, not a file path. webhint analyses the page as served, which is why localhost works as well as a public address. The README points to the online user guide and the local version under packages/hint/docs/user-guide for configuration; the README itself does not enumerate the available hints or their options, so plan to read that guide before deciding the default set is the right one.

Where webhint is the wrong tool

The most obvious limitation is the one built into the design: the documented entry points all operate on a URL. The CLI takes an address, the browser extension works in a browser, and the VS Code extension works in the editor. Nothing in the README describes a mode that lints a directory of source files on its own, and nothing describes a documented exit-code contract you could wire into a CI gate. If your requirement is a check that fails a build before anything is served, that requirement is not answered by what the README shows.

The second limitation is configuration surface. webhint calls itself customizable, and the README repeatedly sends you to the user guide for configuration rather than showing it. That is fine for a team that wants depth, and awkward for a team that wants the default behaviour to be obviously correct. You cannot tell from the README which hints run by default, how noisy they are on a real site, or how to silence one that does not apply to you. Budget time for that first tuning pass.

Finally, the release listing in this repository is old. The most recent release entries shown are dist from 2019-10-01 and two parser packages from 2019-03-07. That does not by itself tell you the project is unmaintained, and the repository is not archived, but it does mean you should not read the releases page as a signal of current activity. The last push to the default branch was on 2026-07-21.

webhint against a general-purpose linter

The natural comparison is with ESLint, which the repository already uses on itself: the root package.json lists eslint, @typescript-eslint/parser and @typescript-eslint/eslint-plugin among its devDependencies, along with eslint-plugin-markdown. The difference in approach matters. ESLint reads source files and applies rules to the syntax it parses, so it can run in a pre-commit hook or a CI job with no server involved. webhint fetches and analyses a served page, so it can see things a static linter cannot: what the browser actually receives, how the page behaves, and whether the delivered result meets a best practice.

That is a real division of labour rather than a competition. A project can keep ESLint for source-level rules and add webhint for the served output. The cost is a second toolchain and a second configuration file, plus the requirement that something is listening on a port when webhint runs. If your pipeline has no running target, ESLint alone will get you further.

Maintenance, licence and the cost of upgrading

The repository is not archived and the last push to the default branch was on 2026-07-21. The release listing shown here is much older, with the newest entry dated 2019-10-01, so the two signals disagree and you should treat the release feed as unreliable evidence either way. For an adopter the useful question is not whether commits happen but whether the packages you install move. Because the monorepo publishes separate npm packages, an upgrade can arrive as a new version of a hint package rather than a new version of the engine, and the README does not document a rollback procedure for that.

The licence is Apache-2.0, stated in the README and shipped as LICENSE.txt at the repository root. Apache-2.0 is a permissive licence with an explicit patent grant, which is generally straightforward for commercial use, but the terms that apply to you depend on how you redistribute the packages, and that is a question for your own counsel rather than for this article. The build path from source requires yarn and is documented as slow, so contributing back is a larger commitment than consuming the published packages.

Editorial conclusion

Adopt webhint if you want a single command that checks accessibility, speed and cross-browser behaviour against a running URL, and you are willing to read the user guide to tune which hints fire. Skip it if you need a build-time linter that fails a pull request without a running server, since the documented entry points are the CLI, the browser extension and the VS Code extension. Before rolling it out, verify two things yourself: that Node.js v14.x or later is present on every machine that will run it, and which hints the default configuration enables for your URL, because the README does not list them.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. webhintio/hint on GitHub