DOCSEARCHbyAlgolia
Submit Docs

vite-plugin-devtools-json

repository·main·Indexed 19 days ago

https://github.com/chromedevtools/vite-plugin-devtools-json

A Vite plugin that automatically generates and serves the com.chrome.devtools.json project settings file at the /.well-known/appspecific/com.chrome.devtools.json endpoint. This enables integration with Chrome DevTools Project Settings and Automatic Workspace folders, featuring support for custom UUIDs, project root configuration, and path normalization for Windows containers (WSL and Docker Desktop).

Tokens
1.4K
Snippets
7
Records
8
Agent score
15%

What's inside vite-plugin-devtools-json

  1. Understand the devtools.json output format

    main

    The plugin serves the project settings at the /.well-known/appspecific/com.chrome.devtools.json endpoint. This JSON structure is used by Chrome DevTools to identify the workspace root and the project UUID.

    {
  "workspace": {
    "root": "/path/to/project/root",
    "uuid": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
  }
}

  2. Use vite-plugin-devtools-json in Vite configuration

    main

    To use the plugin, import devtoolsJson and add it to the plugins array in your vite.config.js or vite.config.ts file. By default, the plugin generates a unique UUID and caches it in the Vite cache folder.

    import {defineConfig} from 'vite';
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson(),
    // ...
  ]
});

  4. How path normalization works for Windows containers

    main

    When running in environments like WSL or Docker Desktop on Windows, Chrome may need paths in UNC format to access files. The plugin provides automatic path rewriting if normalizeForWindowsContainer is enabled (which is the default).

    • WSL: If process.env.WSL_DISTRO_NAME is present, paths are rewritten to \\wsl.localhost\<distro>\<path>.
    • Docker Desktop: If process.env.DOCKER_DESKTOP is present, paths are rewritten to \\wsl.localhost\docker-desktop-data\<path>.

    If normalizeForWindowsContainer is set to false, paths will be served as absolute Linux paths.

  5. Configure devtoolsJson options

    main

    You can pass an options object to devtoolsJson() to customize the generated settings. This is useful for controlling the project root (especially in monorepos), managing UUIDs manually, or ensuring path compatibility with Windows containers.

    import { defineConfig } from 'vite';
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson({
      projectRoot: '/absolute/path/to/project',
      normalizeForWindowsContainer: true,
      uuid: '6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b'
    })
  ]
});

  6. Configure vite-plugin-devtools-json options

    main

    The plugin function accepts an optional DevToolsJsonOptions object to customize how the DevTools workspace is reported.

    OptionTypeDescription
    uuidstringAn optional fixed UUID. If omitted, the plugin generates and caches one automatically in your Vite cacheDir under uuid.json.
    projectRootstringAbsolute or relative path to be reported as the project root in DevTools. Defaults to Vite's config.root logic.
    normalizeForWindowsContainerbooleanWhether to rewrite Linux paths to UNC form (e.g., \\wsl.localhost\...) so Chrome running on Windows (WSL or Docker Desktop) can mount them as a workspace. Enabled by default.
    normalizeForChromebooleanDeprecated. Use normalizeForWindowsContainer instead.
    interface DevToolsJsonOptions {
  uuid?: string;
  projectRoot?: string;
  normalizeForChrome?: boolean; // Deprecated
  normalizeForWindowsContainer?: boolean;
}

  7. Reference: devtoolsJson options

    main

    The following options are available for the devtoolsJson plugin configuration:

    | Name | Type | Default | Description |
|------|------|---------|-------------|
| `projectRoot` | `string` | `config.root` | Absolute path that will be reported to DevTools. Useful for monorepos or when the Vite root is not the desired folder. |
| `normalizeForWindowsContainer` | `boolean` | `true` | Convert Linux paths to UNC form so Chrome on Windows (WSL / Docker Desktop) can mount them (e.g. via WSL or Docker Desktop). Pass `false` to disable. _Alias:_ `normalizeForChrome` (deprecated) |
| `uuid` | `string` | auto-generated | Fixed UUID if you prefer to control it yourself. |

  8. The DevTools JSON data format

    main

    The plugin serves a JSON object at the endpoint /.well-known/appspecific/com.chrome.devtools.json. This object follows the DevToolsJSON schema used by Chrome to identify the workspace:

    {
  "workspace": {
    "root": "/absolute/path/to/project",
    "uuid": "<generated-or-provided-uuid>"
  }
}
    {
  "workspace": {
    "root": "string",
    "uuid": "string"
  }
}