|
| 1 | +# Automatic Workspace Folders |
| 2 | + |
| 3 | +[goo.gle/devtools-automatic-workspace-folders][self-link] |
| 4 | + |
| 5 | +We recently added a new feature to Chromium (available with M-135 and later), |
| 6 | +which improves the ergonomics and discoverability of the [Workspace] feature, |
| 7 | +and it's called "Automatic Workspace Folders". |
| 8 | + |
| 9 | +**Googlers-only:** Check out the internal resources at |
| 10 | + |
| 11 | +- [go/chrome-devtools:automatic-workspace-folders-design][design-doc], and |
| 12 | +- [go/chrome-devtools:automatic-workspace-folders-demo][demo]. |
| 13 | + |
| 14 | +## Background |
| 15 | + |
| 16 | +The [Workspace][workspace-doc] feature, which was originally (re)launched as |
| 17 | +[Workspaces 2.0][workspace-announcement] in M-63 and announced at CDS 2016, |
| 18 | +allows developers to edit and save files in your project, effectively persisting |
| 19 | +changes that you make in DevTools (during debugging) to your source files |
| 20 | +directly. However, as outlined in the documentation this requires quite a bit of |
| 21 | +[manual setup](https://developer.chrome.com/docs/devtools/workspaces#devtools), |
| 22 | +which is |
| 23 | + |
| 24 | +1. not particularly obvious and discoverable, and |
| 25 | +2. not very ergonomic when working on different projects. |
| 26 | + |
| 27 | +Specifically the second point is problematic, as you have to manually maintain |
| 28 | +the list of folders in your workspace, meaning that whenever you work on a new |
| 29 | +project (or just a separate checkout of an existing project) you'd need to add |
| 30 | +the relevant folder manually via the Workspace tab, and when you're done with a |
| 31 | +project (at least for a while) you'd need to remove it explicitly from the list |
| 32 | +(otherwise the list will soon grow very long). |
| 33 | + |
| 34 | +## Solution |
| 35 | + |
| 36 | +With M-135 we've added a feature called "Automatic Workspace Folders", where |
| 37 | +devservers can inform the developer tools running in the browser about the |
| 38 | +project folders that they are serving, and DevTools can automatically pick that |
| 39 | +up and connect to these folders during local debugging, and automatically |
| 40 | +disconnect these folders when the developer navigates somewhere else. |
| 41 | + |
| 42 | +This information is communicated via a special JSON file that DevTools requests |
| 43 | +from a well-known location on the devserver, as outlined in the |
| 44 | +[DevTools Project Settings (devtools.json)][design-doc-json]. The file is named |
| 45 | +`com.chrome.devtools.json` (for now) and located in the |
| 46 | +`/.well-known/appspecific/` folder of the inspected page. For the automatic |
| 47 | +workspace folders, it has to contain a `workspace` object with two properties: |
| 48 | + |
| 49 | +- `workspace.root` is the absolute path to the project folder (where the |
| 50 | + source code is located). |
| 51 | +- `workspace.uuid` is a valid UUID, ideally a v4 UUID, generated randomly when |
| 52 | + setting up the project folder. |
| 53 | + |
| 54 | +An example `com.chrome.devtools.json` would look like this: |
| 55 | + |
| 56 | +``` |
| 57 | +{ |
| 58 | + "workspace": { |
| 59 | + "root": "/Users/foobar/Projects/my-awesome-web-project", |
| 60 | + "uuid": "53b029bb-c989-4dca-969b-835fecec3717" |
| 61 | + } |
| 62 | +} |
| 63 | +``` |
| 64 | + |
| 65 | +Chromium DevTools will only attempt to load the `com.chrome.devtools.json` when |
| 66 | +the origin of the inspected page is `localhost`. |
| 67 | + |
| 68 | +## Setup |
| 69 | + |
| 70 | +In M-135, which is in Canary channel at the time of this writing, and probably |
| 71 | +M-136 too, this feature is disabled by default. To use it, you need to turn on |
| 72 | +two feature flags in `about:flags`: |
| 73 | + |
| 74 | +- [chrome://flags#devtools-project-settings](chrome://flags#devtools-project-settings) |
| 75 | +- [chrome://flags#devtools-automatic-workspace-folders](chrome://flags#devtools-automatic-workspace-folders) |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +Instead of enabling the feature via `about:flags`, you can instead also enable |
| 80 | +them from the command line: |
| 81 | + |
| 82 | +``` |
| 83 | +google-chrome-canary--enable-features=DevToolsWellKnown,DevToolsAutomaticFileSystems |
| 84 | +``` |
| 85 | + |
| 86 | +To check if your setup is correct, you can try out my [Hello World][hello-world] |
| 87 | +demo project. Just follow the steps outlined in the `README.md` there. |
| 88 | + |
| 89 | +[self-link]: http://goo.gle/devtools-automatic-workspace-folders |
| 90 | +[design-doc]: http://go/chrome-devtools:automatic-workspace-folders-design |
| 91 | +[demo]: http://go/chrome-devtools:automatic-workspace-folders-demo |
| 92 | +[workspace-doc]: https://developer.chrome.com/docs/devtools/workspaces |
| 93 | +[workspaces-announcement]: https://developer.chrome.com/blog/new-in-devtools-63#workspaces |
| 94 | +[design-doc-json]: https://goo.gle/devtools-json-design |
| 95 | +[hello-world]: https://github.com/bmeurer/automatic-workspace-folders-hello-world |
0 commit comments