devtools-protocol is a mirror of an interface defined in Chromium, and its issues live on crbug.com

The repository does not own the protocol, and it says so first

The first thing the README does is tell you where the real work happens. It carries a warning that this repository is related to the Chrome DevTools Protocol but does not track issues about its definition or its implementation, and that anyone filing a protocol issue should open it on crbug.com under component Platform>DevTools>Platform, with a link to the Chromium issue entry page.

That single paragraph determines how you should use everything else here. This is a distribution point, not the place where the interface is designed. If a command's semantics are wrong, or a domain is missing a field, filing it against this repository gets it nowhere; the change has to be proposed in Chromium.

The generator reinforces the same point. The TypeScript generator itself lives in Chromium at the path third_party/blink/public/devtools_protocol/scripts/protocol_dts_generator.ts, so that Chromium and this repository share a single source of truth, and the README instructs that changes to the generator should be made in Chromium rather than here.

The practical consequence for an adopter is that a feature you want does not arrive through a pull request to this project. It arrives when Chromium changes and the daily job copies the result out.

Everything under pdl/, json/ and types/ is generated, daily

The repository contents fall into a small number of groups, and all of the interesting ones are machine written. The top-level entries are .github/, .gitignore, .gitmodules, .nvmrc, LICENSE, README.md, changelog.md, json/, package-lock.json, package.json, pdl/, scripts/ and types/.

The Development section is blunt about it: the .pdl files, the json/ files and the TypeScript definitions in types/ are all generated by scripts/update-to-latest.sh, which runs daily, and they must not be edited by hand.

Three artefacts, then. The pdl directory holds the protocol definition in the .pdl format. The json directory holds the protocol as JSON, and the package description calls the project the Chrome DevTools Protocol JSON. The types directory holds the TypeScript definitions.

The daily cadence is the mechanism that keeps the repository honest. Rather than a maintainer merging changes by hand, a scheduled script pulls the current state out of Chromium and rewrites the generated tree, so a checkout of master is close to the current browser. The cost of that design is that a diff in json/ or types/ is not a review signal: it appears on its own schedule and can be large.

A Node version is pinned in .nvmrc, and there is a package-lock.json alongside package.json, so the script's own toolchain is reproducible even though the protocol content is not.

Three ways to consume the types, and which one you want

This is the part that has real design content, and the README is specific about it. The TypeScript definitions for the protocol's types live in types/protocol.d.ts, and mappings from commands and events to those types are available in two different generated styles.

The first is types/protocol-proxy-api.d.ts, described as generated in DomainApi style. The second is types/protocol-mapping.d.ts, described as a simple name to type interface style.

The difference matters in practice, and it is the kind of choice people discover by writing code. A mapping table of names to interfaces is what you want when you are writing a thin client: you look up the event name, get its payload type, and deserialize. A generated proxy API is what you want when you want method calls shaped like the protocol, with each domain exposed as an object whose methods take the command's parameters and whose event handlers receive typed payloads.

Either way, the types are the same underlying definitions, so the choice is about ergonomics rather than coverage. The package.json declares types as types/protocol.d.ts, which is what a consumer's editor picks up by default when the package is installed.

The published package includes three directories in its files array: json, pdl and types. So the raw protocol in both formats and the TypeScript definitions all ship in the same tarball, and the choice of which file to import is left to you.

Regenerating types against a local Chromium checkout

The README documents one local workflow, and it exists for contributors who need types that match a Chromium tree they already have rather than whatever the daily job last copied.

The command is run from the scripts directory and points the build at the protocol scripts inside a local Chromium checkout:

cd scripts
CHROMIUM_PROTOCOL_SCRIPTS_DIR=/path/to/src/third_party/blink/public/devtools_protocol/scripts \
  npm run build-protocol-dts

The environment variable name is the whole interface. The generator is not vendored into this repository; it is read from the path you provide, which is why the checkout is a prerequisite rather than an optional convenience.

The automated script works the same way with a different source. update-to-latest.sh performs a sparse checkout that fetches Chromium into tmp/chromium/, and the README mentions the tmp/ path in describing where the generator is fetched to. A sparse checkout matters at this scale, since a full Chromium clone is not something a scheduled job does every day.

The root also contains a.gitmodules file, although the README does not explain whether the generated files use it.

An npm package whose version is always 0.0.something

The package.json version is 0.0.1718299. The author field is the Chromium Authors, the licence is BSD-3-Clause, the description is the Chrome DevTools Protocol JSON, and the bugs URL points at issues in this repository even though the README says the repository does not track protocol issues.

That version number is the practical hazard for anyone depending on this package. The package is versioned as 0.0.x, which does not provide the compatibility guarantees associated with stable semantic versions.

There is also no GitHub release history. The repository has no releases, so the changelog.md file at the root and the commit history are the record of what changed. The README does not describe a changelog format or a stability policy, and it does not state whether a given domain or command is experimental, deprecated or stable.

The mitigation is mundane and effective: pin an exact version, read changelog.md when you bump, and test against the Chrome build you actually deploy with. A protocol definition generated from Chromium can differ from the version implemented by a browser, so test against the browser you actually deploy with.

When the protocol is the wrong tool

Three cases.

The first is browser coverage. The protocol described here is the Chrome DevTools Protocol, tied to Chromium's internals, and the repository names only Chrome and Chromium as the implementation. If your automation must run against several browser engines with one code path, a protocol defined by one of them is a liability, and a cross-browser approach may be more appropriate.

The second is version skew, and it is the more annoying one. Because the definitions are generated from a moving browser, a client written against today's master may reference commands that the browser your CI machine has does not implement. The failure mode is a call that returns an error at runtime, not a compile error, because the types say the command exists.

The third is scope. The protocol is a low level interface, and using it means owning session lifecycle, target discovery, and the mapping between events and the state you want to observe. For the narrow case of loading a page and reading the DOM, a higher level library that already handles those details will get you there with far less code, at the cost of the fine control this repository exposes.

Licence, governance and the cost of depending on generated output

The licence is BSD-3-Clause with a LICENSE file at the root, attributed to the Chromium Authors. No legal advice is offered, but a permissive licence on a generated artefact is about as permissive as it gets, and the attribution requirement is satisfied by carrying the notice.

Governance is the more interesting cost. The generator lives in Chromium, while this repository regenerates and publishes the output. Changes to the generator should be made in Chromium; the generated files here should not be edited by hand.

The upgrade cost follows from that. You are not upgrading a library with hand written code and a semantic version policy; you are tracking an interface that Chrome itself changes. That is a real advantage when you want new browser capabilities without waiting for anyone to wrap them, and a real burden when you want your dependency to stay put.

What the repository does not provide is a compatibility table, a list of experimental domains, or any statement about deprecation policy. The protocol viewer at chromedevtools.github.io/devtools-protocol is named in the README as the way to navigate the protocol, and that, rather than the repository, is the reference to read before designing around a domain.

Editorial conclusion

Depend on the devtools-protocol package when you are writing TypeScript that talks to Chrome's debugging interface and want the official generated types rather than hand written ones, and pin an exact version. Do not treat this repository as a place to report protocol problems, because the README states it does not track issues and directs them to crbug.com under component Platform>DevTools>Platform. Verify first that the domains you plan to use are marked the way you need, and remember that the files under pdl/, json/ and types/ are generated by a daily script and should not be edited by hand, so a local change there will be overwritten.

Frequently asked questions

Official sources

1. ChromeDevTools/devtools-protocol on GitHub
2. Issues
3. License: BSD-3-Clause
4. Project website
5. README