feat: Add a dev overlay (#8757)

* feat: initial commit for dev overlay * fix: lockfile * fix: build * chore: get ci in a better state * feat: client-server communication * fix: better position for xray * refactor: move icons to separate files * refactor: cleanup components * feat: home screen * refactor: rename icon * feat: flag the feature * fix: cleanup * fix: lockfile * feat: minimize button * Update packages/astro/src/@types/astro.ts Co-authored-by: Sarah Rainsberger <[email protected]> * refactor: cleanup * feat: add ability to go to component for hydrated components * refactor: consistent logic between audit and xray * chore: changeset * Apply suggestions from code review Co-authored-by: Chris Swithinbank <[email protected]> Co-authored-by: Nate Moore <[email protected]> * fix: unchonky the SVGs * fix: button a11y * refactor: move common highlight utilities to a dedicated file * fix: allow tabbing on highlights * fix: allow tooltip clickable sections to be tabbed to * feat: allow using defined icons as plugin icons * refactor: remove unnecessary resolve * Update .changeset/large-stingrays-fry.md Co-authored-by: Sarah Rainsberger <[email protected]> * Update .changeset/large-stingrays-fry.md Co-authored-by: Sarah Rainsberger <[email protected]> * nit: use append * style: small tweaks to minimize button styling --------- Co-authored-by: Sarah Rainsberger <[email protected]> Co-authored-by: Chris Swithinbank <[email protected]> Co-authored-by: Nate Moore <[email protected]>
withastro · Oct 25, 2023 · e995867 · e995867
1 parent 4740d76
commit e995867
Show file tree

Hide file tree

Showing 20 changed files with 1,341 additions and 1 deletion.
diff --git a/.changeset/large-stingrays-fry.md b/.changeset/large-stingrays-fry.md
@@ -0,0 +1,21 @@
+---
+'astro': minor
+---
+
+
+Dev Overlay (experimental)
+
+Provides a new dev overlay for your browser preview that allows you to inspect your page islands, see helpful audits on performance and accessibility, and more. A Dev Overlay Plugin API is also included to allow you to add new features and third-party integrations to it.
+
+You can enable access to the dev overlay and its API by adding the following flag to your Astro config:
+
+```ts
+// astro.config.mjs
+export default {
+  experimental: {
+    devOverlay: true
+  }
+};
+```
+
+Read the [Dev Overlay Plugin API documentation](https://docs.astro.build/en/reference/dev-overlay-plugin-reference/) for information about building your own plugins to integrate with Astro's dev overlay.
diff --git a/.eslintrc.cjs b/.eslintrc.cjs
@@ -1,5 +1,7 @@
+// eslint-disable-next-line @typescript-eslint/no-var-requires
 const { builtinModules } = require('module');
 
+/** @type {import("@types/eslint").Linter.Config} */
 module.exports = {
   extends: [
     'plugin:@typescript-eslint/recommended-type-checked',
@@ -74,6 +76,12 @@ module.exports = {
         ],
       },
     },
+    {
+      files: ['packages/astro/src/runtime/client/**/*.ts'],
+      env: {
+        browser: true,
+      },
+    },
     {
       files: ['packages/**/test/*.js', 'packages/**/*.js'],
       env: {

diff --git a/.github/scripts/bundle-size.mjs b/.github/scripts/bundle-size.mjs
@@ -68,6 +68,7 @@ async function bundle(files) {
 		sourcemap: false,
 		target: ['es2018'],
 		outdir: 'out',
+		external: ['astro:*'],
 		metafile: true,
 	})
 

diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts
@@ -21,6 +21,7 @@ import type { TSConfig } from '../core/config/tsconfig.js';
 import type { AstroCookies } from '../core/cookies/index.js';
 import type { ResponseWithEncoding } from '../core/endpoint/index.js';
 import type { AstroIntegrationLogger, Logger, LoggerLevel } from '../core/logger/core.js';
+import type { Icon } from '../runtime/client/dev-overlay/ui-library/icons.js';
 import type { AstroComponentFactory, AstroComponentInstance } from '../runtime/server/index.js';
 import type { OmitIndexSignature, Simplify } from '../type-utils.js';
 import type { SUPPORTED_MARKDOWN_FILE_EXTENSIONS } from './../core/constants.js';
@@ -1351,6 +1352,25 @@ export interface AstroUserConfig {
 		 * ```
 		 */
 		optimizeHoistedScript?: boolean;
+
+		/**
+		 * @docs
+		 * @name experimental.devOverlay
+		 * @type {boolean}
+		 * @default `false`
+		 * @version 3.4.0
+		 * @description
+		 * Enable a dev overlay in development mode. This overlay allows you to inspect your page islands, see helpful audits on performance and accessibility, and more.
+		 *
+		 * ```js
+		 * {
+		 * 	experimental: {
+		 * 		devOverlay: true,
+		 * 	},
+		 * }
+		 * ```
+		 */
+		devOverlay?: boolean;
 	};
 }
 
@@ -1524,6 +1544,7 @@ export interface AstroSettings {
 	 * Map of directive name (e.g. `load`) to the directive script code
 	 */
 	clientDirectives: Map<string, string>;
+	devOverlayPlugins: string[];
 	tsConfig: TSConfig | undefined;
 	tsConfigPath: string | undefined;
 	watchFiles: string[];
@@ -2049,6 +2070,7 @@ export interface AstroIntegration {
 			injectScript: (stage: InjectedScriptStage, content: string) => void;
 			injectRoute: (injectRoute: InjectedRoute) => void;
 			addClientDirective: (directive: ClientDirectiveConfig) => void;
+			addDevOverlayPlugin: (entrypoint: string) => void;
 			logger: AstroIntegrationLogger;
 			// TODO: Add support for `injectElement()` for full HTML element injection, not just scripts.
 			// This may require some refactoring of `scripts`, `styles`, and `links` into something
@@ -2284,3 +2306,17 @@ export interface ClientDirectiveConfig {
 	name: string;
 	entrypoint: string;
 }
+
+export interface DevOverlayPlugin {
+	id: string;
+	name: string;
+	icon: Icon;
+	init?(canvas: ShadowRoot, eventTarget: EventTarget): void | Promise<void>;
+}
+
+export type DevOverlayMetadata = Window &
+	typeof globalThis & {
+		__astro_dev_overlay__: {
+			root: string;
+		};
+	};
diff --git a/packages/astro/src/core/config/schema.ts b/packages/astro/src/core/config/schema.ts
@@ -55,6 +55,7 @@ const ASTRO_CONFIG_DEFAULTS = {
 	redirects: {},
 	experimental: {
 		optimizeHoistedScript: false,
+		devOverlay: false,
 	},
 } satisfies AstroUserConfig & { server: { open: boolean } };
 
@@ -297,6 +298,7 @@ export const AstroConfigSchema = z.object({
 				.boolean()
 				.optional()
 				.default(ASTRO_CONFIG_DEFAULTS.experimental.optimizeHoistedScript),
+			devOverlay: z.boolean().optional().default(ASTRO_CONFIG_DEFAULTS.experimental.devOverlay),
 		})
 		.strict(
 			`Invalid or outdated experimental feature.\nCheck for incorrect spelling or outdated Astro version.\nSee https://docs.astro.build/en/reference/configuration-reference/#experimental-flags for a list of all current experiments.`

diff --git a/packages/astro/src/core/config/settings.ts b/packages/astro/src/core/config/settings.ts
@@ -98,6 +98,7 @@ export function createBaseSettings(config: AstroConfig): AstroSettings {
 		scripts: [],
 		clientDirectives: getDefaultClientDirectives(),
 		watchFiles: [],
+		devOverlayPlugins: [],
 		timer: new AstroTimer(),
 	};
 }

diff --git a/packages/astro/src/core/create-vite.ts b/packages/astro/src/core/create-vite.ts
@@ -16,6 +16,7 @@ import astroPostprocessVitePlugin from '../vite-plugin-astro-postprocess/index.j
 import { vitePluginAstroServer } from '../vite-plugin-astro-server/index.js';
 import astroVitePlugin from '../vite-plugin-astro/index.js';
 import configAliasVitePlugin from '../vite-plugin-config-alias/index.js';
+import astroDevOverlay from '../vite-plugin-dev-overlay/vite-plugin-dev-overlay.js';
 import envVitePlugin from '../vite-plugin-env/index.js';
 import astroHeadPlugin from '../vite-plugin-head/index.js';
 import htmlVitePlugin from '../vite-plugin-html/index.js';
@@ -134,6 +135,7 @@ export async function createVite(
 			vitePluginSSRManifest(),
 			astroAssetsPlugin({ settings, logger, mode }),
 			astroTransitions(),
+			astroDevOverlay({ settings, logger }),
 		],
 		publicDir: fileURLToPath(settings.config.publicDir),
 		root: fileURLToPath(settings.config.root),

diff --git a/packages/astro/src/integrations/index.ts b/packages/astro/src/integrations/index.ts
@@ -125,6 +125,9 @@ export async function runHookConfigSetup({
 				addWatchFile: (path) => {
 					updatedSettings.watchFiles.push(path instanceof URL ? fileURLToPath(path) : path);
 				},
+				addDevOverlayPlugin: (entrypoint) => {
+					updatedSettings.devOverlayPlugins.push(entrypoint);
+				},
 				addClientDirective: ({ name, entrypoint }) => {
 					if (updatedSettings.clientDirectives.has(name) || addedClientDirectives.has(name)) {
 						throw new Error(