DevTools Project Settings (devtools.json)
Attention: Externally visible, non-confidential
Authors: Benedikt Meurer Adam Raine
Status: Done
Short Link: goo.gle/devtools-json-design (go/chrome-devtools:devtools-json-design)
Launch: launch/4376003
Created: 2025-02-07 / Last Updated: 2025-06-30
We propose to introduce a devtools.json file to communicate information from a devserver (e.g. vite) to the debugger during local debugging. The MVP will communicate the local folder of the project to Chrome DevTools (to automatically connect it via the Workspaces feature), and associate field data with local development sites (as described in go/cpq:field-data-dev-origins).
Desktop.
Chrome DevTools
The idea dates back to 2020 (proposal draft by Stefan Wallner), and the core idea is that by introducing this mechanism, we can significantly reduce the amount of work required by developers to set up Chrome DevTools to maximize their productivity. This idea also addresses the issue that many cool features, such as the Workspaces feature are barely discoverable.
“DevTools front-end”.
Name | Approval status |
Danil Somsikov (DevTools TL) | LGTM |
Alex Rudenko (Tooling Intelligence TL) | LGTM |
Paul Irish (Performance Tooling TL) | LGTM |
We propose to introduce a JSON file (com.chrome.devtools.json), in a well-known location, to be consumed by Chrome DevTools during local development.
We propose introducing a new JSON-based file format that can be used by devservers to communicate information about the project to the debugger.
{
"workspace": {
"root": "/absolute/path/to/workspace",
"uuid": "project-id",
},
"deployment": {
"url": "http://www.example.com/articles/",
"pathMappings": [
{
"path": "/",
"url": "https://example.com/articles/",
},
{
"path": "/some/special/dev/path/",
"url": "https://special.com/",
}
]
}
}
The optional "workspace.uuid" and "workspace.root" can be used by Chrome DevTools to enable developers to automatically connect the project folder via the Workspaces feature (assuming user consent).
go/chrome-devtools:automatic-workspace-folders-design provides more information about the details here.
To get field data for a site, CrUX needs to know the production URL of that site to get the correct data set. This can be complicated for dev sites hosted on localhost or staging environments.
The current method for resolving the production URL for a dev site involves using an origin mapping table, but this does not cover all use cases. Instead of using an origin mapping table, the com.chrome.devtools.json file could provide the production URL for dev sites as described in go/cpq:field-data-dev-origins.
We propose to define a Well-Known URI for the JSON file (per IETF RFC8615, previously RFC5785), in the form of /.well-known/appspecific/com.chrome.devtools.json (following the Well-known URI for application-specific purposes specification).
Chrome DevTools will look for the /.well-known/appspecific/com.chrome.devtools.json file on the primary target’s main frame (as identified by ResourceTreeModel.mainFrame) whenever the inspected URL changes, but only when that frames’ security origin is considered local. In order to determine that, we propose to change CDP (Chrome DevTools Protocol) such that:
The file will be loaded through the PageResourceLoader, using the primary target and its main frame’s ID, and this request will therefore show up in the Developer resources panel.
The retrieval of the file will be gated by a dedicated base::Feature named DevToolsWellKnown, which is going to be disabled by default initially. Use --enable-features=DevToolsWellKnown on the command line to enable the feature.
We might want to consider exposing this feature to chrome://flags.
We propose to introduce a new internal front-end API in the form of a ProjectSettingsModel singleton (in a new models/project_settings module), that has a change event, and deals with the retrieval of the project settings file, and access to its contents.
go/cpq:field-data-dev-origins already lists various options how the field data configuration could look like, including special HTTP headers, special <meta> tags, special performance.mark entries, or some combination thereof. These mechanisms could of course also be used for the workspace root configuration. But we believe that the JSON file approach is the most future proof and is also the easiest to set up, because even if the devserver one is using doesn’t support this out of the box, it’s just a matter of dropping a file in the right location.
We also considered other Well-Known URIs for the JSON file, like /.well-known/devtools.json, and we will likely re-open the discussion around that again at some point, but for the MVP it’s easiest to just stick to an application-specific Well-Known URI.
We propose to roll out this feature gradually as follows:
N/A
We only retrieve the com.chrome.devtools.json file from local origins. Also this proposal is not concerned with how the data is consumed exactly, and is therefore considered neutral wrt. security.
As outlined above, we believe that the combination of JSON file format and Well-Known URI location is the simplest possible solution, as it’s very easy to reason about it, and even if devservers don’t support this natively, it’s just a matter of creating a simple file in a specific location.
N/A
In the context of go/chrome-devtools:automatic-workspace-folders-design, the settings loaded from the JSON file will be used to automatically connect (project) folders to the workspace.
In the context of go/cpq:field-data-dev-origins, the settings loaded from the JSON file will be used to retrieve and correlate the corresponding field data for the local development site.
If this approach proves successful we will engage with other debugging tools and the wider ecosystem to come up with a standard.
We also need to prepare documentation for developers about the devtools.json format and how to utilize it.