@monocle.sh/vite-plugin 0.2.1 → 0.3.0

package/README.md

@@ -70,14 +70,28 @@ unless it is one of the placeholders above.
 
 ## How it works
 
-The plugin prepends `globalThis.__MONOCLE_BUILD__ = {…}` to each of your modules
-that imports `@monocle.sh/browser-sdk`. The SDK reads it in `initMonocle()`.
-
-This targets application code rather than relying on `define`, which Vite does
-not apply to pre-bundled dependencies. It needs no inline `<script>`, so it
-works with SSR frameworks that don't use `index.html` and with strict CSPs.
-During SSR, the global is also set on the server, where the Browser SDK stays
-inactive.
+When every entry of `vite build` is an HTML page (the default `index.html`
+setup), the plugin writes the release into the page as
+`<meta name="monocle-build" content="{…}">`, which the SDK reads in
+`initMonocle()`. Your JavaScript chunks never contain the release, so two builds
+of the same code produce identical chunks, file names and debug IDs: a deploy
+only uploads the source maps of the chunks that changed. A `<meta>` tag is not
+affected by Content Security Policies. This needs `@monocle.sh/browser-sdk`
+0.13.0 or later; with an older SDK the plugin warns and falls back to the
+bundle.
+
+Otherwise (dev server, SSR, library builds, frameworks rendering the HTML
+themselves), the plugin prepends `globalThis.__MONOCLE_BUILD__ = {…}` to each of
+your modules that imports `@monocle.sh/browser-sdk`. This targets application
+code rather than relying on `define`, which Vite does not apply to pre-bundled
+dependencies. During SSR, the global is also set on the server, where the
+Browser SDK stays inactive.
+
+Vite and Rolldown also put the hashed file name of every imported chunk into
+the importing chunk, so changing one chunk renames the chunks that import it,
+up to the entry. To keep those unchanged too, enable Vite's
+[`build.chunkImportMap`](https://vite.dev/config/build-options) (Vite 8,
+experimental).
 
 ## Source maps
 

package/dist/vite.d.mts

@@ -60,6 +60,7 @@ interface MonocleSourcemapsOptions {
  * Translate Vite hooks to the bundler-agnostic Monocle build.
  */
 declare class MonocleVitePlugin {
+  #private;
   static create(options?: MonoclePluginOptions): Plugin;
 }
 /**

package/dist/vite.mjs

@@ -1,8 +1,51 @@
-import { dirname, join, resolve } from "node:path";
-import { readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve, sep } from "node:path";
+import { readFileSync, realpathSync, statSync } from "node:fs";
 import MagicString from "magic-string";
 import { rm } from "node:fs/promises";
 import { injectDebugIds, uploadSourcemaps } from "@monocle.sh/sourcemaps";
+//#region src/core/browser_sdk.ts
+/**
+* What the Browser SDK the application resolves can read.
+*/
+var BrowserSdk = class {
+	/**
+	* First `@monocle.sh/browser-sdk` reading `<meta name="monocle-build">`.
+	*/
+	static pageReleaseSince = "0.13.0";
+	static #atLeast(version, minimum) {
+		const parse = (value) => value.split(/[-+]/)[0].split(".").map(Number);
+		const [actual, expected] = [parse(version), parse(minimum)];
+		for (let index = 0; index < 3; index++) {
+			const difference = (actual[index] ?? 0) - (expected[index] ?? 0);
+			if (Number.isNaN(difference)) return false;
+			if (difference !== 0) return difference > 0;
+		}
+		return true;
+	}
+	/**
+	* Where the installed SDK reads the release: `page` from the HTML, `bundle` only from the
+	* global, `missing` when the application does not resolve it, so nothing reads a page tag. A
+	* linked local copy (workspace) is assumed current; one that cannot be inspected (Yarn PnP
+	* archives…) reads the bundle.
+	*/
+	static releaseSource(root) {
+		let path;
+		try {
+			path = createRequire(join(root, "package.json")).resolve("@monocle.sh/browser-sdk/package.json");
+		} catch {
+			return "missing";
+		}
+		try {
+			if (!realpathSync(path).includes(`${sep}node_modules${sep}`)) return "page";
+			const { version } = JSON.parse(readFileSync(path, "utf8"));
+			return typeof version === "string" && this.#atLeast(version, this.pageReleaseSince) ? "page" : "bundle";
+		} catch {
+			return "bundle";
+		}
+	}
+};
+//#endregion
 //#region ../otel-utils/dist/service-version.mjs
 var ServiceVersionDetector = class {
 	/**
@@ -327,7 +370,10 @@ var BuildMetadataResolver = class {
 //#endregion
 //#region src/core/release_injection.ts
 /**
-* Prepend a global assignment to every module importing the Browser SDK.
+* Expose the release to the Browser SDK. Builds with an HTML page write it into a
+* `<meta name="monocle-build">` tag: JavaScript chunks then stay byte-identical between builds of
+* the same code, so their hashes and debug IDs do too. Other builds (SSR, library, dev server)
+* prepend a global assignment to every module importing the Browser SDK.
 *
 * Import declarations are hoisted, so the SDK module is evaluated first, but it only reads the
 * global when `initMonocle()` runs, which always happens after the importing module starts
@@ -339,6 +385,10 @@ var ReleaseInjection = class {
 	* Read by `@monocle.sh/browser-sdk`. Keep both sides in sync.
 	*/
 	static globalName = "__MONOCLE_BUILD__";
+	/**
+	* Name of the `<meta>` tag the Browser SDK reads when the global is not set.
+	*/
+	static metaName = "monocle-build";
 	static sdkImport = /["']@monocle\.sh\/browser-sdk(?:\/[^"'\s]*)?["']/;
 	/**
 	* Stylesheets, markup and data can mention the package without being JavaScript. Markup is
@@ -353,6 +403,15 @@ var ReleaseInjection = class {
 	static snippet(metadata) {
 		return `globalThis.${this.globalName}=${JSON.stringify(metadata)};`;
 	}
+	/**
+	* URI-encoded JSON: without quotes, it survives Vite 5, which does not escape attributes.
+	*/
+	static meta(metadata) {
+		return {
+			name: this.metaName,
+			content: encodeURIComponent(JSON.stringify(metadata))
+		};
+	}
 	static shouldInject(options) {
 		return !this.nonScriptIds.test(options.id) && this.sdkImport.test(options.code);
 	}
@@ -409,6 +468,13 @@ var MonocleBuild = class {
 		this.#log(value);
 		return value;
 	}
+	/**
+	* The release for the `<meta>` tag of an HTML page, when injection is on.
+	*/
+	pageMetadata() {
+		if (!this.enabled || this.#options.options.inject === false) return;
+		return this.resolve();
+	}
 	transform(options) {
 		if (!this.enabled || this.#options.options.inject === false) return;
 		if (!ReleaseInjection.shouldInject(options)) return;
@@ -529,12 +595,47 @@ var SourcemapsStep = class {
 /**
 * Translate Vite hooks to the bundler-agnostic Monocle build.
 */
-var MonocleVitePlugin = class {
+var MonocleVitePlugin = class MonocleVitePlugin {
+	/**
+	* Client builds whose every entry is an HTML page, the only ones where the release can live
+	* in the page instead of the chunks. Vite builds `index.html` without an explicit input.
+	* Frameworks rendering the HTML themselves set another input, per environment since Vite 6.
+	*/
+	static #htmlBuild(config) {
+		const { build } = config;
+		if (config.consumer === "server" || build.ssr || build.lib) return false;
+		const input = (build.rolldownOptions ?? build.rollupOptions)?.input;
+		if (input === void 0) return true;
+		const entries = typeof input === "string" ? [input] : Object.values(input);
+		return entries.length > 0 && entries.every((entry) => /\.html?$/.test(entry));
+	}
 	static create(options = {}) {
 		const plugin = { name: "@monocle.sh/vite-plugin" };
 		if (options.enabled === false) return plugin;
 		let build;
 		let resolved;
+		let sdkReadsPage;
+		/**
+		* Whether the release can go into the HTML pages of this build: a build with injection on,
+		* for an installed Browser SDK reading the page. Detected once, with a warning for older
+		* SDKs. Without the SDK, nothing reads a page tag: none is written.
+		*/
+		function pageSupported() {
+			if (!resolved || resolved.command !== "build" || options.inject === false) return false;
+			if (sdkReadsPage === void 0) {
+				const source = BrowserSdk.releaseSource(resolved.root);
+				sdkReadsPage = source === "page";
+				if (source === "bundle") resolved.logger.warn(`[monocle] @monocle.sh/browser-sdk < ${BrowserSdk.pageReleaseSince} reads the release from the bundle only, so every build changes all chunk hashes. Upgrade it to keep unchanged chunks identical.`);
+			}
+			return sdkReadsPage;
+		}
+		/**
+		* Whether modules of this environment leave the release to its HTML page. Vite 5 has no
+		* environments: the top-level configuration applies.
+		*/
+		function releaseInPage(environment) {
+			return !!resolved && MonocleVitePlugin.#htmlBuild(environment?.config ?? resolved) && pageSupported();
+		}
 		const sourcemaps = new SourcemapsStep({
 			options,
 			env: process.env
@@ -576,6 +677,7 @@ var MonocleVitePlugin = class {
 					code: ReleaseInjection.sdkImport
 				},
 				handler(code, id) {
+					if (releaseInPage(this.environment)) return;
 					return build?.transform({
 						code,
 						id
@@ -583,6 +685,20 @@ var MonocleVitePlugin = class {
 				}
 			},
 			/**
+			* Builds only call it for HTML entries. When some modules still got the global (mixed
+			* HTML and script entries), the SDK prefers the global, so the tag is harmless.
+			*/
+			transformIndexHtml() {
+				if (!pageSupported()) return;
+				const metadata = build?.pageMetadata();
+				if (!metadata) return;
+				return [{
+					tag: "meta",
+					attrs: ReleaseInjection.meta(metadata),
+					injectTo: "head-prepend"
+				}];
+			},
+			/**
 			* Sequential and last, so compression or copy plugins see the injected files.
 			*/
 			writeBundle: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monocle.sh/vite-plugin",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Vite plugin that injects your release into the Monocle Browser SDK and uploads source maps at build time",
   "keywords": [
     "monocle",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "magic-string": "^0.30.21",
-    "@monocle.sh/sourcemaps": "^0.1.0"
+    "@monocle.sh/sourcemaps": "^0.2.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",
@@ -49,7 +49,7 @@
     "tsdown": "^0.21.10",
     "vite": "^8.3.4",
     "vue": "^3.5.44",
-    "@monocle.sh/browser-sdk": "0.12.0",
+    "@monocle.sh/browser-sdk": "0.13.0",
     "@monocle.sh/otel-utils": "1.9.0"
   },
   "peerDependencies": {