modernweb-dev/web: Web Test Runner and Web Dev Server for browser-first projects

What modernweb-dev/web actually ships

The repository is a monorepo, not a single package. Its README lists two products: Web Test Runner and Web Dev Server. Everything else in the repo, the guides, the docs directory, the integration and test-helpers folders, exists to support those two tools and the writing around them. The root package.json is named @web/root and marked private, which tells you the repository is a workspace root rather than something you install directly. Individual packages live under packages/ and are published under the @web scope, as the recent release list shows with @web/test-runner-puppeteer, @web/test-runner-chrome and @web/dev-server-core.

The stated goal is to work with the browser first. The README puts it as wanting to work closely with the browser and avoid complex abstractions, and the three bullets under the description make the same argument: built on web standards, lightweight, low complexity. That is a positioning choice with a real consequence. If your build pipeline is a bundler that transforms everything before the browser sees it, these tools are not trying to replace that layer. They assume the browser can run your code, or something close to it.

The audience follows from that. It is for teams writing components, web components in particular given the topics and the surrounding ecosystem, and for anyone who wants a dev server and a test runner that do not require a framework-specific toolchain in between.

How Web Dev Server and Web Test Runner relate to each other

The repository layout makes the split visible. packages/dev-server holds the server, packages/test-runner holds the runner, and the root has a web-test-runner.config.mjs, which is the configuration file the runner reads. The runner depends on the server rather than duplicating its job, so the same resolution and transformation behaviour applies whether you are developing or testing. That is the mechanism worth understanding: the dev server serves your source files with minimal transformation, and the test runner starts that server, points a browser at the test page, and collects results.

Browser launchers are separate packages. The release list shows @web/test-runner-chrome and @web/test-runner-puppeteer at version 1.0.1, published on 2026-07-27. That pattern means browser support is a dependency choice, not something baked into the core runner. The repository topics mention browserstack and saucelabs, and the README credits both as supporters, which points at remote browser testing as a supported direction. The README does not document the configuration for those remote services, so check the docs site before assuming a specific setup.

The dev server core is also published separately as @web/dev-server-core, same version and date. If you are building tooling that needs the server's middleware without the CLI, that is the package to look at. The README does not describe the middleware API, so treat this as a pointer, not a tutorial.

Installing modernweb-dev/web packages and running a first test

The repository itself is not the thing you install. You install the individual @web packages into your own project. The README points at modern-web.dev/docs/ for the documentation, and the packages are published on npm under the @web scope. Note the engine requirement first: the root package.json declares Node >=22.0.0, so check your local and CI Node versions before anything else.

The README does not include an install snippet, and the repository's own install script is written for contributors rather than consumers. The repository's start script is the only runnable command the files show for the dev server:

node packages/dev-server/dist/bin.js --root-dir _site --open

That is the start:build script from the root package.json. It runs the built dev server binary against a _site directory and opens a browser. For a consumer project the equivalent is the published CLI, but the README does not print that command, so check the Web Dev Server docs for the exact invocation rather than copying this one, which assumes the monorepo has already been built with npm run build.

For the test runner, the repository root contains a file named web-test-runner.config.mjs. That filename is the one fact the files give you about configuring the runner. The README does not show its contents, so the config keys you need are in the Web Test Runner docs, not here. The root package.json shows the test script running test:node, test:browser and test:storybook-builder in sequence, which tells you the project splits its own test runs by environment, but those scripts are for the monorepo, not for your project.

The Node 22 floor and the monorepo shape are real constraints

The engines field in the root package.json requires Node >=22.0.0. That is a hard floor for anyone building or contributing to the repository, and it is worth checking whether it also applies to consumers of the published packages. The README does not state the consumer-side requirement, and the individual package manifests are not shown here, so this is a genuine unknown. If you are on an older LTS line, verify before you plan a migration.

The second constraint is structural. This is a workspace monorepo with a build step that runs tsc --build across packages and a changesets-based release flow, visible in the release script and the .changeset directory. That is normal for a project of this size, but it means contributing is not a matter of editing one file. The build:clean script wipes tsconfig.tsbuildinfo and dist across all packages, and the reinstall-workspace script removes every package's node_modules before reinstalling. Expect a full rebuild after a fresh clone.

Where it is the wrong tool: if your tests need a Node runtime rather than a browser, Web Test Runner is aimed at the browser side. The repository's products are a browser test runner and a dev server. It is not a general-purpose Node test framework, and nothing in the README suggests otherwise.

How this differs from a framework-bundled dev server and test setup

The obvious comparison is a framework's own dev server and test tooling, which typically arrive with a bundler, a transform pipeline and a test runner wired together. The difference here is the starting assumption. modernweb-dev/web starts from what the browser can already do and adds the minimum on top. The README frames this as working with the browser rather than against it, and argues that fewer abstraction layers make debugging easier and keep skills relevant longer.

That trade-off cuts both ways. A framework-bundled setup will handle TypeScript, JSX and asset imports out of the box because the bundler is already there. With Web Dev Server you get a server that serves your files and a resolution plugin, and anything beyond that is a plugin you configure. The README acknowledges this directly, saying the project is aware that not all problems can be solved elegantly by the browser today, and that it supports developers making informed decisions about adding tools and customizations so they can upgrade later as browser support improves. That is an honest framing, and it also tells you the project expects you to add plugins.

The other alternative is a full browser-automation stack such as Playwright or Puppeteer used directly. Those give you a browser control API and expect you to build the test harness. Web Test Runner is the opposite: it provides the harness and the serving layer, and delegates browser control to launcher packages, which is why @web/test-runner-puppeteer exists as a separate published package.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-25. The most recent releases are three 1.0.1 versions published on 2026-07-27: @web/test-runner-puppeteer, @web/test-runner-chrome and @web/dev-server-core. The 1.0.x version numbers on the core packages suggest the API surface has stabilised, though the README does not make any compatibility promise.

Upgrade cost is shaped by the release tooling. The repository uses changesets, visible in the .changeset directory and the release script that runs changeset publish. Changesets produce per-package version bumps and changelogs, which means you can upgrade the runner and the launchers independently. That is useful if you only need a new browser launcher, and it is also a reason to pin versions rather than float them, since the packages version separately.

The licence is MIT, declared in both the LICENSE file and the root package.json. MIT is permissive: it allows commercial use and modification with attribution and no warranty. That is a summary of what the licence identifier means, not legal advice. If your organisation has rules about which licences are acceptable in dependencies, the MIT identifier is the fact to check against them. The README does not describe a contributor licence agreement or any additional terms.

Editorial conclusion

Adopt it if your code already runs in a browser and you want a test runner and dev server that sit on top of that rather than replacing it; the monorepo layout and Node >=22 engine field are the first things to check against your CI image. Skip it if you need a Node-side test runner, since the repository's products are Web Test Runner and Web Dev Server and nothing else. Before committing, read the docs pages for both products and confirm the browser launcher packages you need are published under the @web scope.

Frequently asked questions

Official sources

1. License: MIT
2. modernweb-dev/web on GitHub
3. Project website
4. README
5. Releases