feat: add automatic chrome workspace handling (#14122)

Co-authored-by: Sarah Rainsberger <[email protected]>


Co-authored-by: florian-lefebvre <[email protected]>
Co-authored-by: delucis <[email protected]>
Co-authored-by: sarah11918 <[email protected]>
Co-authored-by: ematipico <[email protected]>
Co-authored-by: bjohansebas <[email protected]>

Author: 6 people

.changeset/plain-dragons-bow.md

@@ -0,0 +1,24 @@
+---
+'astro': minor
+---
+
+Adds experimental support for automatic [Chrome DevTools workspace folders](https://developer.chrome.com/docs/devtools/workspaces)
+
+This feature allows you to edit files directly in the browser and have those changes reflected in your local file system via a connected workspace folder. This allows you to apply edits such as CSS tweaks without leaving your browser tab!
+
+With this feature enabled, the Astro dev server will automatically configure a Chrome DevTools workspace for your project. Your project will then appear as a workspace source, ready to connect. Then, changes that you make in the "Sources" panel are automatically saved to your project source code.
+
+To enable this feature, add the experimental flag `chromeDevtoolsWorkspace` to your Astro config:
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  experimental: {
+    chromeDevtoolsWorkspace: true,
+  },
+});
+```
+
+See the [experimental Chrome DevTools workspace feature documentation](https://docs.astro.build/en/reference/experimental-flags/chrome-devtools-workspace/) for more information.

packages/astro/src/core/config/schemas/base.ts

@@ -103,6 +103,7 @@ export const ASTRO_CONFIG_DEFAULTS = {
 		liveContentCollections: false,
 		csp: false,
 		rawEnvValues: false,
+		chromeDevtoolsWorkspace: false,
 	},
 } satisfies AstroUserConfig & { server: { open: boolean } };
 
@@ -502,6 +503,10 @@ export const AstroConfigSchema = z.object({
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.csp),
 			rawEnvValues: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.experimental.rawEnvValues),
+			chromeDevtoolsWorkspace: z
+				.boolean()
+				.optional()
+				.default(ASTRO_CONFIG_DEFAULTS.experimental.chromeDevtoolsWorkspace),
 		})
 		.strict(
 			`Invalid or outdated experimental feature.\nCheck for incorrect spelling or outdated Astro version.\nSee https://docs.astro.build/en/reference/experimental-flags/ for a list of all current experiments.`,

packages/astro/src/types/public/config.ts

@@ -2458,6 +2458,31 @@ export interface ViteUserConfig extends OriginalViteUserConfig {
 		 * See the [experimental raw environment variables guide](https://docs.astro.build/en/reference/experimental-flags/raw-env-values/) for more information.
 		 */
 		rawEnvValues?: boolean;
+		/**
+		 * @name experimental.chromeDevtoolsWorkspace
+		 * @type {boolean}
+		 * @default `false`
+		 * @version 5.13
+		 * @description
+		 *
+		 * Enables Chrome DevTools workspace integration for the Astro dev server.
+		 *
+		 * When enabled, the dev server will automatically configure a [Chrome DevTools workspace](https://developer.chrome.com/docs/devtools/workspaces) for your project,
+		 * allowing you to edit files directly in the browser and have those changes reflected in your local file system.
+		 *
+		 * ```js
+		 * import { defineConfig } from 'astro/config';
+		 *
+		 * export default defineConfig({
+		 *   experimental: {
+		 *     chromeDevtoolsWorkspace: true,
+		 *   },
+		 * });
+		 * ```
+		 *
+		 * See the [experimental Chrome DevTools workspace feature documentation](https://docs.astro.build/en/reference/experimental-flags/chrome-devtools-workspace/) for more information.
+		 */
+		chromeDevtoolsWorkspace?: boolean;
 	};
 }
 

packages/astro/src/vite-plugin-astro-server/plugin.ts

@@ -1,5 +1,8 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
 import type fs from 'node:fs';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { IncomingMessage } from 'node:http';
 import { fileURLToPath } from 'node:url';
 import type * as vite from 'vite';
@@ -135,6 +138,44 @@ export default function createVitePluginAstroServer({
 					route: '',
 					handle: trailingSlashMiddleware(settings),
 				});
+
+				// Chrome DevTools workspace handler
+				// See https://chromium.googlesource.com/devtools/devtools-frontend/+/main/docs/ecosystem/automatic_workspace_folders.md
+				viteServer.middlewares.use(async function chromeDevToolsHandler(request, response, next) {
+					if (request.url !== '/.well-known/appspecific/com.chrome.devtools.json') {
+						return next();
+					}
+					if (!settings.config.experimental.chromeDevtoolsWorkspace) {
+						// Return early to stop console spam
+						response.writeHead(404);
+						response.end();
+						return;
+					}
+
+					const cacheDir = settings.config.cacheDir;
+					const configPath = new URL('./chrome-workspace.json', cacheDir);
+
+					if (!existsSync(cacheDir)) {
+						await mkdir(cacheDir, { recursive: true });
+					}
+
+					let config;
+					try {
+						config = JSON.parse(await readFile(configPath, 'utf-8'));
+					} catch {
+						config = {
+							version: '1.0',
+							projectId: randomUUID(),
+							workspaceRoot: fileURLToPath(settings.config.root),
+						};
+						await writeFile(configPath, JSON.stringify(config));
+					}
+
+					response.setHeader('Content-Type', 'application/json');
+					response.end(JSON.stringify(config));
+					return;
+				});
+
 				// Note that this function has a name so other middleware can find it.
 				viteServer.middlewares.use(async function astroDevHandler(request, response) {
 					if (request.url === undefined || !request.method) {

packages/astro/test/chrome-devtools-workspace.test.js

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import { after, before, describe, it } from 'node:test';
+import { loadFixture } from './test-utils.js';
+
+describe('Chrome DevTools workspace', () => {
+	describe('with experimental flag enabled', () => {
+		let fixture;
+		let devServer;
+
+		before(async () => {
+			fixture = await loadFixture({
+				root: './fixtures/astro-dev-headers/',
+				experimental: {
+					chromeDevtoolsWorkspace: true,
+				},
+			});
+			devServer = await fixture.startDevServer();
+		});
+
+		after(async () => {
+			await devServer.stop();
+		});
+
+		it('serves Chrome DevTools workspace endpoint', async () => {
+			const result = await fixture.fetch('/.well-known/appspecific/com.chrome.devtools.json');
+			assert.equal(result.status, 200);
+			assert.equal(result.headers.get('content-type'), 'application/json');
+
+			const data = await result.json();
+			assert.equal(data.version, '1.0');
+			assert.equal(typeof data.projectId, 'string');
+			assert.equal(data.projectId.length, 36); // UUID length
+			assert.equal(typeof data.workspaceRoot, 'string');
+			assert.ok(data.workspaceRoot.includes('astro-dev-headers'));
+		});
+	});
+
+	describe('with experimental flag disabled', () => {
+		let fixture;
+		let devServer;
+
+		before(async () => {
+			fixture = await loadFixture({
+				root: './fixtures/astro-dev-headers/',
+				experimental: {
+					chromeDevtoolsWorkspace: false,
+				},
+			});
+			devServer = await fixture.startDevServer();
+		});
+
+		after(async () => {
+			await devServer.stop();
+		});
+
+		it('returns 404 for Chrome DevTools workspace endpoint', async () => {
+			const result = await fixture.fetch('/.well-known/appspecific/com.chrome.devtools.json');
+			assert.equal(result.status, 404);
+		});
+	});
+});