### HTTP Request Example

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/endpoints.md

This is an example of an HTTP GET request to the DevTools endpoint. It shows the method, path, and host.

```http
GET /.well-known/appspecific/com.chrome.devtools.json HTTP/1.1
Host: localhost:5173
```

--------------------------------

### Configure Plugin with All Options

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/README.md

Example demonstrating how to configure the plugin with all available options: projectRoot, normalizeForWindowsContainer, and uuid.

```javascript
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'
    })
  ]
});
```

--------------------------------

### Example Response from Docker Desktop on Windows

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/endpoints.md

This example illustrates the response format when running within Docker Desktop on Windows, also showing the UNC path format.

```json
{
  "workspace": {
    "root": "\\wsl.localhost\\docker-desktop-data\\workspace\\project",
    "uuid": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
  }
}
```

--------------------------------

### Example Response from WSL

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/endpoints.md

This example shows the response format when the project is running within Windows Subsystem for Linux (WSL), with the path converted to UNC format.

```json
{
  "workspace": {
    "root": "\\wsl.localhost\\Ubuntu-22.04\\home\\user\\my-react-app",
    "uuid": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
  }
}
```

--------------------------------

### Plugin Setup for Monorepo with Custom Project Root

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/plugin-factory.md

Use this configuration for monorepo setups to specify a custom project root directory.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      projectRoot: path.resolve(__dirname, '../')
    }),
  ]
});
```

--------------------------------

### Install vite-plugin-devtools-json

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/README.md

Install the plugin as a development dependency using npm.

```bash
npm install -D vite-plugin-devtools-json
```

--------------------------------

### Basic Plugin Setup

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/plugin-factory.md

Integrate the plugin into your Vite configuration with default settings.

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

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

--------------------------------

### Plugin Setup with All Options

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/plugin-factory.md

Configure the plugin with all available options: UUID, custom project root, and path normalization.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      uuid: '550e8400-e29b-41d4-a716-446655440000',
      projectRoot: path.resolve(__dirname, '../'),
      normalizeForWindowsContainer: true
    }),
  ]
});
```

--------------------------------

### Install vite-plugin-devtools-json with PNPM

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Use this command to install the plugin as a development dependency using PNPM.

```bash
pnpm add -D vite-plugin-devtools-json
```

--------------------------------

### Install vite-plugin-devtools-json with Yarn

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Use this command to install the plugin as a development dependency using Yarn.

```bash
yarn add --dev vite-plugin-devtools-json
```

--------------------------------

### Running Vite Dev Server vs. Preview Server

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Demonstrates the correct command to start the Vite development server and contrasts it with the incorrect command for previewing a production build.

```bash
# ✅ Correct - starts dev server
npm run dev

# ❌ Wrong - starts preview server (returns 404)
npm run build && npm run preview
```

--------------------------------

### Example DevToolsJSON Response

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/types.md

An example of the JSON response that the plugin provides at the /.well-known/appspecific/com.chrome.devtools.json endpoint.

```json
{
  "workspace": {
    "root": "/home/user/my-project",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

--------------------------------

### Verify UNC Path Format for Windows

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Example of a correct UNC path format for workspace root when running on Windows, often required for WSL or Docker.

```json
{
  "workspace": {
    "root": "\\wsl.localhost\Ubuntu\home\user\project",
    "uuid": "..."
  }
}
```

--------------------------------

### Example Successful Response

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/endpoints.md

A typical successful response from the DevTools endpoint, showing a local project path and a generated UUID.

```json
{
  "workspace": {
    "root": "/home/user/my-react-app",
    "uuid": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
  }
}
```

--------------------------------

### Plugin Setup with Fixed UUID

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/plugin-factory.md

Configure the plugin with a specific UUID for identification.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      uuid: '550e8400-e29b-41d4-a716-446655440000'
    }),
  ]
});
```

--------------------------------

### Successful Response (200 OK) Example

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/endpoints.md

This JSON structure represents a successful response from the DevTools endpoint, including workspace root and UUID.

```json
{
  "workspace": {
    "root": "/absolute/path/to/project/root",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

--------------------------------

### Monorepo Vite Setup with Devtools JSON Plugin

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/REFERENCE-INDEX.md

Configure the plugin for monorepo projects by specifying the `projectRoot` option. This helps the plugin correctly resolve paths within the monorepo structure.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      projectRoot: path.resolve(__dirname, '../../')
    })
  ]
});
```

--------------------------------

### Basic Vite Setup with Devtools JSON Plugin

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/REFERENCE-INDEX.md

Standard configuration for integrating the vite-plugin-devtools-json into a Vite project. Ensure the plugin is imported and included in the `plugins` array of your `vite.config.ts`.

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

export default defineConfig({
  plugins: [devtoolsJson()]
});
```

--------------------------------

### CI/CD Vite Setup with Fixed UUID

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/REFERENCE-INDEX.md

Use a fixed UUID for CI/CD environments by providing it via an environment variable (`PROJECT_UUID`). This bypasses the plugin's default UUID generation and caching logic.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      uuid: process.env.PROJECT_UUID || undefined
    })
  ]
});
```

--------------------------------

### Verify WSL Path Conversion

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Use curl to check the endpoint response for correct path formatting in WSL environments. Expected paths should start with \\wsl.localhost.

```bash
curl http://localhost:5173/.well-known/appspecific/com.chrome.devtools.json
```

--------------------------------

### GET /.well-known/appspecific/com.chrome.devtools.json

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/endpoints.md

Serves the Chrome DevTools project settings JSON file. This endpoint is available only on the development server and enables automatic workspace discovery and integration with Chrome DevTools.

```APIDOC
## GET /.well-known/appspecific/com.chrome.devtools.json

### Description
Serves the Chrome DevTools project settings JSON file that enables automatic workspace discovery and integration.

### Method
GET

### Endpoint
/.well-known/appspecific/com.chrome.devtools.json

### Parameters
This endpoint accepts no request parameters, query strings, or request bodies.

### Request Example
```http
GET /.well-known/appspecific/com.chrome.devtools.json HTTP/1.1
Host: localhost:5173
```

### Response
#### Success Response (200 OK)
- **Content-Type**: `application/json; charset=UTF-8`

#### Response Schema
- **workspace** (object) - Required - Container for workspace metadata.
  - **workspace.root** (string) - Required - Absolute file system path to the project root directory. On Windows systems (WSL or Docker Desktop), this is converted to UNC format (e.g., `\\wsl.localhost\Ubuntu\path\to\project`). Subject to the `projectRoot` configuration option and path normalization settings.
  - **workspace.uuid** (string) - Required - Unique identifier (UUID v4) for the project workspace. Used by Chrome DevTools to maintain stable project identity across dev server restarts. Either the fixed UUID from plugin options or an auto-generated and cached UUID.

#### Response Example
```json
{
  "workspace": {
    "root": "/home/user/my-react-app",
    "uuid": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
  }
}
```

#### Example Response from WSL
```json
{
  "workspace": {
    "root": "\\wsl.localhost\\Ubuntu-22.04\\home\\user\\my-react-app",
    "uuid": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
  }
}
```

#### Example Response from Docker Desktop on Windows
```json
{
  "workspace": {
    "root": "\\wsl.localhost\\docker-desktop-data\\workspace\\project",
    "uuid": "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"
  }
}
```
```

--------------------------------

### Plugin Setup Disabling Path Normalization

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/plugin-factory.md

Disable path normalization for Windows containers by setting 'normalizeForWindowsContainer' to false.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      normalizeForWindowsContainer: false
    }),
  ]
});
```

--------------------------------

### Configure Vite Plugin DevTools JSON

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/README.md

Example of how to integrate vite-plugin-devtools-json into your Vite configuration. You can optionally provide a fixed UUID, project root, or enable/disable path normalization for Windows containers.

```typescript
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson({
      uuid?: string;                    // Fixed UUID or auto-generate
      projectRoot?: string;             // Project root path
      normalizeForWindowsContainer?: boolean;  // Path conversion (default: true)
    })
  ]
});
```

--------------------------------

### Detect Docker Desktop Environment

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/path-normalization.md

Check for the DOCKER_DESKTOP environment variable to detect if the code is running within Docker Desktop. Also, ensure the path does not already start with '\\' to prevent double conversion.

```typescript
if (process.env.DOCKER_DESKTOP && !absRoot.startsWith('\\')) {
  // ... apply Docker Desktop path conversion ...
}
```

--------------------------------

### Absolute vs. Relative Workspace Paths

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Illustrates the correct format for an absolute workspace root path compared to an incorrect relative path.

```json
{
  "workspace": {
    "root": "/absolute/path",  // ✅ Good
    "uuid": "..."
  }
}

Not:
{
  "workspace": {
    "root": "./relative/path",  // ❌ Bad
    "uuid": "..."
  }
}
```

--------------------------------

### Build Output Serving Configuration

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

When serving a build output directory, set `projectRoot` to `process.cwd()` to report the actual project root, not the build root.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      projectRoot: process.cwd()  // Report actual project root, not build root
    })
  ]
});
```

--------------------------------

### Example UUID in HTTP Response

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/uuid-caching.md

The UUID is included in the JSON response served by the endpoint, used for identifying the workspace.

```json
{
  "workspace": {
    "root": "/home/user/project",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

--------------------------------

### Vite Root ≠ Project Root Configuration

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

When Vite's root is in a subdirectory, configure `projectRoot` to point to the actual project root.

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

export default defineConfig({
  root: './',
  plugins: [
    devtoolsJson({
      projectRoot: path.resolve(__dirname, '../')  // Point to my-app/
    })
  ]
});
```

--------------------------------

### Vite Plugin Devtools JSON with All Options

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/configuration.md

Demonstrates the configuration with all available options set: a fixed UUID, a custom project root, and path normalization enabled.

```typescript
import path from 'path';

export default defineConfig({
  plugins: [
    devtoolsJson({
      uuid: '550e8400-e29b-41d4-a716-446655440000',
      projectRoot: path.resolve(__dirname, '../'),
      normalizeForWindowsContainer: true
    })
  ]
});
```

--------------------------------

### Plugin Factory and Configuration

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/README.md

Demonstrates how to import and configure the vite-plugin-devtools-json plugin within your Vite configuration file.

```APIDOC
### Plugin Configuration

To use the plugin, import it and add it to your `vite.config.js` or `vite.config.ts` file.

```typescript
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson({
      uuid?: string;                    // Fixed UUID or auto-generate
      projectRoot?: string;             // Project root path
      normalizeForWindowsContainer?: boolean;  // Path conversion (default: true)
    })
  ]
});
```

#### Configuration Options

| Option | Type | Default | Purpose |
|--------|------|---------|---------|
| `uuid` | string | auto-generated | Fixed UUID for the project |
| `projectRoot` | string | `config.root` | Project root path to report |
| `normalizeForWindowsContainer` | boolean | `true` | Enable Windows path conversion |
```

--------------------------------

### Configure Vite Plugin for Docker Desktop on Windows

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

This configuration is for Docker Desktop on Windows. The plugin detects the Docker environment and converts paths for Chrome access via Docker Desktop integration.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      // normalizeForWindowsContainer: true  // default
    })
  ]
});
```

--------------------------------

### Multiple Vite Configurations

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Configure the plugin for projects with multiple Vite configurations, such as separate configurations for an app and a library. Each configuration can have its own `projectRoot` and `uuid`.

```typescript
// vite.app.config.ts
import { defineConfig } from 'vite';
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson({
      projectRoot: './app',
      uuid: 'app-uuid-...'
    })
  ]
});

// vite.lib.config.ts
import { defineConfig } from 'vite';
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson({
      projectRoot: './lib',
      uuid: 'lib-uuid-...'
    })
  ]
});
```

--------------------------------

### Get or Create Project UUID

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/middleware-handlers.md

Retrieves a project-specific UUID, either from options or by generating and caching it. It resolves the cache directory, checks for an existing valid UUID file, and creates one if necessary, ensuring consistency across restarts.

```typescript
const getOrCreateUUID = () => {
  if (options.uuid) {
    return options.uuid;
  }
  // Cache directory resolution...
  let {cacheDir} = config;
  if (!path.isAbsolute(cacheDir)) {
    let {root} = config;
    if (!path.isAbsolute(root)) {
      root = path.resolve(process.cwd(), root);
    }
    cacheDir = path.resolve(root, cacheDir);
  }
  const uuidPath = path.resolve(cacheDir, 'uuid.json');
  if (fs.existsSync(uuidPath)) {
    const uuid = fs.readFileSync(uuidPath, {encoding: 'utf-8'});
    if (validate(uuid)) {
      return uuid;
    }
  }
  if (!fs.existsSync(cacheDir)) {
    fs.mkdirSync(cacheDir, {recursive: true});
  }
  const uuid = v4();
  fs.writeFileSync(uuidPath, uuid, {encoding: 'utf-8'});
  return uuid;
};
```

--------------------------------

### HTTP Endpoint for Workspace Information

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/REFERENCE-INDEX.md

This endpoint provides workspace details including the project root and a unique identifier. It is available in development mode and returns a 404 in preview mode.

```APIDOC
## GET /.well-known/appspecific/com.chrome.devtools.json

### Description
Retrieves workspace information, including the project root and a UUID. This endpoint is primarily for development mode.

### Method
GET

### Endpoint
`/.well-known/appspecific/com.chrome.devtools.json`

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **workspace** (object) - Contains workspace details.
  - **root** (string) - The absolute path to the project root.
  - **uuid** (string) - A unique identifier for the workspace.

#### Response Example
```json
{
  "workspace": {
    "root": "/absolute/path/to/project",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```
```

--------------------------------

### Plugin Hook: configurePreviewServer

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/middleware-handlers.md

The `configurePreviewServer` hook registers a middleware that always responds with a 404 for the DevTools JSON endpoint when the preview server is initialized. This ensures the endpoint is disabled in preview mode.

```typescript
configurePreviewServer(server) {
  server.middlewares.use(ENDPOINT, async (req, res) => {
    res.writeHead(404);
    res.end();
  });
}
```

--------------------------------

### Running Multiple Vite Configs

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Execute separate Vite development servers for each configuration file. This allows each server to serve its own endpoint with distinct project metadata.

```bash
vite -c vite.app.config.ts --port 5173
vite -c vite.lib.config.ts --port 5174
```

--------------------------------

### Enable Path Normalization

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/path-normalization.md

Set `normalizeForWindowsContainer` to `true` to enable path normalization. This is the default behavior.

```typescript
devtoolsJson({
  normalizeForWindowsContainer: true  // or false to disable
})
```

--------------------------------

### Custom Project Root Resolution

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Implement custom logic to determine the project root. This is useful when the default resolution doesn't match your project structure. The plugin will use the returned path or fallback to its default if undefined.

```typescript
const resolveProjectRoot = () => {
  // Custom logic here
  if (process.env.CUSTOM_PROJECT_ROOT) {
    return process.env.CUSTOM_PROJECT_ROOT;
  }
  // Fallback to plugin default
  return undefined;
};

export default defineConfig({
  plugins: [
    devtoolsJson({
      projectRoot: resolveProjectRoot() || undefined
    })
  ]
});
```

--------------------------------

### Normalize Path for WSL and Docker Desktop

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/middleware-handlers.md

Normalizes absolute paths for compatibility with WSL and Docker Desktop on Windows. If `normalizePaths` is false, the path is returned unchanged. It rewrites paths to a UNC format like `\\wsl.localhost\{distro}\{path}` or `\\wsl.localhost\docker-desktop-data\{path}`.

```typescript
const maybeNormalizePath = (absRoot: string): string => {
  if (!normalizePaths) return absRoot;

  // WSL path rewrite
  if (process.env.WSL_DISTRO_NAME) {
    const distro = process.env.WSL_DISTRO_NAME;
    const withoutLeadingSlash = absRoot.replace(/^\\/, '');
    return path
      .join('\\wsl.localhost', distro, withoutLeadingSlash)
      .replace(/\//g, '\\');
  }

  // Docker Desktop on Windows path rewrite
  if (process.env.DOCKER_DESKTOP && !absRoot.startsWith('\\')) {
    const withoutLeadingSlash = absRoot.replace(/^\\/, '');
    return path
      .join('\\wsl.localhost', 'docker-desktop-data', withoutLeadingSlash)
      .replace(/\//g, '\\');
  }

  return absRoot;
};
```

--------------------------------

### Configure Vite Plugin for Mixed Teams

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Configure path normalization dynamically for mixed development teams. Set FORCE_NO_PATH_NORMALIZATION=1 to disable normalization for specific users or environments.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      normalizeForWindowsContainer: process.env.FORCE_NO_PATH_NORMALIZATION !== '1'
    })
  ]
});
```

--------------------------------

### Add Plugin to Vite Config

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/README.md

Import and add the plugin to your Vite configuration file.

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

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

--------------------------------

### Register Preview Server Handler

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/middleware-handlers.md

Registers a middleware to handle requests to the DevTools JSON endpoint in preview mode. This handler always responds with a 404 status code.

```typescript
server.middlewares.use(ENDPOINT, async (req, res) => {
  res.writeHead(404);
  res.end();
});
```

--------------------------------

### Vite Plugin Integration

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/REFERENCE-INDEX.md

Demonstrates how to import and use the vite-plugin-devtools-json in your Vite configuration file. This is the primary way to enable the plugin's features.

```typescript
import devtoolsJson from 'vite-plugin-devtools-json';

export default defineConfig({
  plugins: [
    devtoolsJson({ /* options */ })
  ]
});
```

--------------------------------

### Plugin Factory Function Signature

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/plugin-factory.md

The main export is a function that accepts optional configuration and returns a Vite Plugin.

```typescript
function devtoolsJson(options?: DevToolsJsonOptions): Plugin
```

--------------------------------

### Use Legacy Path Normalization Option

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/path-normalization.md

The `normalizeForChrome` option is deprecated and should be replaced by `normalizeForWindowsContainer`. A deprecation warning will be emitted if this option is used.

```typescript
devtoolsJson({
  normalizeForChrome: true  // deprecated, use normalizeForWindowsContainer
})
```

--------------------------------

### Enable Windows Container Path Normalization

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Configure the devtoolsJson plugin to normalize paths for Windows containers, essential for WSL and Docker environments.

```typescript
devtoolsJson({
  normalizeForWindowsContainer: true  // Should be true or omitted
})
```

--------------------------------

### Migrate from Deprecated normalizeForChrome

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/configuration.md

Update configuration to use `normalizeForWindowsContainer` instead of the deprecated `normalizeForChrome` option for backward compatibility.

```typescript
// Old (deprecated)
devtoolsJson({ normalizeForChrome: false })

// New (recommended)
devtoolsJson({ normalizeForWindowsContainer: false })
```

--------------------------------

### Create Cache Directory if Not Exists

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/uuid-caching.md

Ensures the cache directory exists before writing the UUID cache file. It creates the directory recursively if it's missing.

```typescript
if (!fs.existsSync(cacheDir)) {
  fs.mkdirSync(cacheDir, {recursive: true});
}
```

--------------------------------

### Check Vite Cache Directory for UUID

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Inspect the Vite cache directory to check for the presence of the UUID file and verify directory permissions.

```bash
# Check cache directory
ls -la .vite/uuid.json

# If missing, verify directory permissions
ls -la .vite/
```

--------------------------------

### Configure Vite Plugin for WSL

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Use this configuration in vite.config.ts for WSL environments. The plugin automatically handles path conversion for Chrome integration.

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

export default defineConfig({
  plugins: [
    devtoolsJson({
      // normalizeForWindowsContainer: true  // default, can be omitted
    })
  ]
});
```

--------------------------------

### HTTP Endpoint for DevTools Integration

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/README.md

This endpoint serves project settings for Chrome DevTools workspace discovery. It is active only in development mode and returns a 404 in preview mode.

```APIDOC
## GET /.well-known/appspecific/com.chrome.devtools.json

### Description
Serves project settings for Chrome DevTools workspace discovery. This endpoint is only active in development mode.

### Method
GET

### Endpoint
`/.well-known/appspecific/com.chrome.devtools.json`

### Response
#### Success Response (200)
- **workspace** (object) - Contains workspace information.
  - **root** (string) - The absolute path to the project root.
  - **uuid** (string) - The unique identifier for the workspace.

### Response Example
```json
{
  "workspace": {
    "root": "/absolute/path/to/project",
    "uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```
```

--------------------------------

### Enable Path Normalization (Default)

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/path-normalization.md

Set `normalizeForWindowsContainer` to `true` when your Vite dev server is running in WSL or Docker on Windows, and you are using Chrome DevTools on Windows. This converts paths to UNC format for seamless workspace mounting.

```typescript
devtoolsJson({
  normalizeForWindowsContainer: true  // or omit for default
})
```

--------------------------------

### Resolve Project Root Path

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/middleware-handlers.md

Resolves the project root directory. It prioritizes an explicitly provided `projectRoot` option, otherwise it uses Vite's `config.root`, resolving it to an absolute path if it's relative to the current working directory.

```typescript
const resolveProjectRoot = (): string => {
  if (options.projectRoot) {
    return path.resolve(options.projectRoot);
  }
  let {root} = config;
  if (!path.isAbsolute(root)) {
    root = path.resolve(process.cwd(), root);
  }
  return root;
};
```

--------------------------------

### CI/CD Integration with Fixed UUID

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Use a fixed UUID for reproducible builds in CI environments. Path normalization is disabled as CI typically doesn't run Chrome on Windows.

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

const FIXED_UUID = '550e8400-e29b-41d4-a716-446655440000';

export default defineConfig({
  plugins: [
    devtoolsJson({
      uuid: FIXED_UUID,
      normalizeForWindowsContainer: false  // CI doesn't need WSL conversion
    })
  ]
});
```

--------------------------------

### Plugin Options Interface

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/configuration.md

Defines the available configuration options for the devtoolsJson plugin. All options are optional.

```typescript
devtoolsJson({
  uuid?: string;
  projectRoot?: string;
  normalizeForWindowsContainer?: boolean;
  normalizeForChrome?: boolean;  // deprecated
})
```

--------------------------------

### DevToolsJsonOptions

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/types.md

Configuration object passed to the plugin factory function to customize behavior.

```APIDOC
## DevToolsJsonOptions

### Description
Configuration object passed to the plugin factory function to customize behavior.

### Fields

#### uuid
- **Type**: `string`
- **Required**: No
- **Description**: A fixed UUID (v4 format) for the project. If omitted, the plugin generates and caches one automatically. Must be a valid UUID v4 string if provided.

#### projectRoot
- **Type**: `string`
- **Required**: No
- **Description**: Absolute or relative path to the project root reported to Chrome DevTools. Defaults to Vite's `config.root`. Useful for monorepos or when the Vite root differs from the desired project workspace root.

#### normalizeForChrome
- **Type**: `boolean`
- **Required**: No
- **Description**: **Deprecated** — Use `normalizeForWindowsContainer` instead. Controls path normalization for Windows containers. Provides backward compatibility; a deprecation warning is logged if used alone.

#### normalizeForWindowsContainer
- **Type**: `boolean`
- **Required**: No
- **Description**: Whether to rewrite Linux paths to UNC format for Windows environments (WSL, Docker Desktop). Defaults to `true`. When enabled, automatically detects WSL and Docker Desktop environments and converts paths accordingly.

### Accepted By
- `devtoolsJson()` function — the main plugin factory
```

--------------------------------

### Detect WSL Environment

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/path-normalization.md

Check for the WSL_DISTRO_NAME environment variable to detect if the code is running within the Windows Subsystem for Linux. Apply WSL path conversion logic if detected.

```typescript
if (process.env.WSL_DISTRO_NAME) {
  const distro = process.env.WSL_DISTRO_NAME;
  // ... apply WSL path conversion ...
}
```

--------------------------------

### Construct and Send DevTools JSON Response

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/middleware-handlers.md

Constructs the DevTools JSON configuration object, including the normalized project root and UUID. It sets the 'Content-Type' header to 'application/json' and sends the serialized JSON response.

```typescript
let root = maybeNormalizePath(resolveProjectRoot());
const uuid = getOrCreateUUID();
const devtoolsJson: DevToolsJSON = {
  workspace: {
    root,
    uuid,
  }
};
res.setHeader('Content-Type', 'application/json');
res.end(JSON.stringify(devtoolsJson, null, 2));
```

--------------------------------

### Default UUID Generation and Caching

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/uuid-caching.md

Uses the default behavior to generate a UUID on first startup and cache it to `.vite/uuid.json`. This UUID persists across dev server restarts and machine reboots.

```typescript
devtoolsJson()  // No options
```

--------------------------------

### Verify Docker Desktop Environment Variable

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Check if the DOCKER_DESKTOP environment variable is set inside the Docker container.

```bash
echo $DOCKER_DESKTOP  # Should output 'true'
```

--------------------------------

### Set Project Root Path

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/configuration.md

Specify the project root path for DevTools JSON output. This is useful in monorepos or when Vite's root differs from the actual workspace.

```typescript
import path from 'path';

devtoolsJson({
  projectRoot: path.resolve(__dirname, '../')
})
```

```typescript
devtoolsJson({
  projectRoot: process.env.PROJECT_ROOT || undefined
})
```

--------------------------------

### Plugin Hook: configureServer

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/middleware-handlers.md

The `configureServer` hook is used to register development server middleware. It includes a check to ensure middleware is only registered in development mode (`config.env.DEV === true`).

```typescript
const plugin = (options: DevToolsJsonOptions = {}): Plugin => ({
  name: 'devtools-json',
  enforce: 'post',

  configureServer(server) {
    const {config} = server;
    const {logger} = config;

    if (!config.env.DEV) {
      return;  // Exit early if not in development mode
    }
    
    // ... handler registration ...
  },
  
  configurePreviewServer(server) {
    // ... preview handler registration ...
  }
});
```

--------------------------------

### Minimal Vite Plugin Devtools JSON Configuration

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/configuration.md

Uses all default settings for the plugin. The UUID is auto-generated and cached, the project root is Vite's default, and path normalization is enabled.

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

export default defineConfig({
  plugins: [
    devtoolsJson()
  ]
});
```

--------------------------------

### Configure Plugin with Custom UUID

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/README.md

Optionally, provide a specific UUID for the plugin in your Vite configuration.

```javascript
  plugins: [
    devtoolsJson({ uuid: "6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b" }),
    // ...
  ]
```

--------------------------------

### Load UUID from File

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Reads the UUID from a `.devtools.json` configuration file. This approach centralizes UUID management in a separate file. Falls back to auto-generation if the file is not found or cannot be parsed.

```json
// .devtools.json
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}
```

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import devtoolsJson from 'vite-plugin-devtools-json';
import { readFileSync } from 'fs';
import { join } from 'path';

const devtoolsConfig = (() => {
  try {
    const config = JSON.parse(
      readFileSync(join(__dirname, '.devtools.json'), 'utf-8')
    );
    return { uuid: config.uuid };
  } catch {
    return {};  // Fallback to auto-generation
  }
})();

export default defineConfig({
  plugins: [
    devtoolsJson(devtoolsConfig)
  ]
});
```

--------------------------------

### Error Response Header

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/endpoints.md

This is the HTTP response header returned when the endpoint is accessed during preview or build mode, resulting in a 404 Not Found status.

```http
HTTP/1.1 404 Not Found
```

--------------------------------

### DevToolsJsonOptions Interface

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/path-normalization.md

Configuration options for the DevToolsJson plugin, including path normalization settings.

```APIDOC
## DevToolsJsonOptions

### normalizeForWindowsContainer

**Type**: `boolean`

**Default**: `true`

**Description**: Controls whether Linux file paths are automatically converted to Windows UNC format when running in containerized or WSL environments. Set to `false` to disable this feature.

### normalizeForChrome (Deprecated)

**Type**: `boolean`

**Default**: `true`

**Description**: A legacy option for backward compatibility. Use `normalizeForWindowsContainer` instead. A deprecation warning will be emitted if this option is used without `normalizeForWindowsContainer`.

**Precedence**: 
1. `normalizeForWindowsContainer` takes precedence.
2. If not set, `normalizeForChrome` is used.
3. If neither is set, the default (`true`) is used.

### Example Usage
```typescript
import devtoolsJson from 'vite-plugin-devtools-json';

export default {
  plugins: [
    devtoolsJson({
      normalizeForWindowsContainer: true // or false to disable
    })
  ]
]
}
```
```

--------------------------------

### Deprecation Warning for normalizeForChrome

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/api-reference/middleware-handlers.md

Logs a deprecation warning if the 'normalizeForChrome' option is used in isolation without 'normalizeForWindowsContainer'. This ensures users are prompted to migrate to the newer option.

```typescript
// Emit deprecation warning if old option is used in isolation.
if (
  Object.prototype.hasOwnProperty.call(options, 'normalizeForChrome') &&
  options.normalizeForWindowsContainer === undefined
) {
  logger.warn(
    '[vite-plugin-devtools-json] "normalizeForChrome" is deprecated – please rename to "normalizeForWindowsContainer".'
  );
}
```

--------------------------------

### Verify Endpoint Response with cURL

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Use cURL to manually check the response from the DevTools endpoint while the dev server is running.

```bash
# While dev server is running
curl http://localhost:5173/.well-known/appspecific/com.chrome.devtools.json
```

--------------------------------

### CI/CD Integration with Environment Variables

Source: https://github.com/chromedevtools/vite-plugin-devtools-json/blob/main/_autodocs/INTEGRATION-GUIDE.md

Configure devtoolsJson based on environment variables. Provides a default UUID if PROJECT_UUID is not set in CI.

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

const getDevtoolsConfig = () => {
  if (process.env.CI) {
    return {
      uuid: process.env.PROJECT_UUID || '550e8400-e29b-41d4-a716-446655440000',
      normalizeForWindowsContainer: false
    };
  }
  
  return {
    normalizeForWindowsContainer: true
  };
};

export default defineConfig({
  plugins: [
    devtoolsJson(getDevtoolsConfig())
  ]
});
```