@monocle.sh/vite-plugin 0.1.0 → 0.2.1

package/README.md

@@ -4,6 +4,9 @@ Detects your release when Vite builds or serves your app, and hands it to
 [`@monocle.sh/browser-sdk`](../browser-sdk). Monocle then sees each new version
 of your front end as a deployment, without setting `serviceVersion` by hand.
 
+After each production build, it also gives your bundles debug IDs and uploads
+their source maps, so Monocle shows errors with your original code.
+
 ## Installation
 
 ```sh
@@ -40,7 +43,7 @@ Empty values and the placeholders `0.0.0`, `0.0.1`, `1.0.0`, `unknown`, `dev`,
 and `latest` are skipped. When available, the commit SHA, repository URL
 (credentials removed) and platform deployment ID are attached too.
 
-The plugin makes no network calls, and only reads the variables above.
+Release detection makes no network calls, and only reads the variables above.
 
 ## Options
 
@@ -50,9 +53,18 @@ monocle({
   inject: true, // expose the release to the Browser SDK
   enabled: true, // turn the whole plugin off
   verbose: false, // log the detected release and its source
+  sourcemaps: {
+    apiKey: process.env.MONOCLE_API_KEY, // default; without a key nothing is uploaded
+    apiUrl: 'https://api.monocle.sh',
+    release: 'v2.4.0', // shown next to the files, defaults to the detected release
+    deleteAfterUpload: true, // default when the plugin enabled source maps itself
+    failOnError: false, // log upload errors instead of failing the build
+  },
 })
 ```
 
+Pass `sourcemaps: false` to turn source map handling off.
+
 A `serviceVersion` passed to `initMonocle()` wins over the injected release,
 unless it is one of the placeholders above.
 
@@ -66,3 +78,32 @@ 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.
+
+## Source maps
+
+During `vite build`, the plugin:
+
+1. Turns on `build.sourcemap: 'hidden'` if you haven't configured
+   `build.sourcemap` and an API key is set. Maps are generated without a
+   `sourceMappingURL` comment, so browsers never request them. An explicit
+   `build.sourcemap: false` disables the steps below. With
+   `build.sourcemap: true`, it logs a warning: the bundles reference their maps,
+   so browsers can download them.
+2. Once the bundle is written, injects a debug ID into each JavaScript chunk
+   and its map with [`@monocle.sh/sourcemaps`](../sourcemaps). A one-line
+   snippet registers the ID, and the Browser SDK sends it with every error.
+3. With an API key (`sourcemaps.apiKey` or `MONOCLE_API_KEY`), uploads each
+   chunk and its map. Files Monocle already has are skipped. Missing sources
+   are only embedded from source files inside the Vite `root`. Without a key, it
+   only injects the maps you configured and logs a hint.
+4. Deletes the `.map` files if the plugin turned source maps on itself, even
+   when the upload fails, so they are never deployed. Set
+   `deleteAfterUpload: false` to keep them, or `true` to delete the maps you
+   configured after a successful upload.
+
+Upload errors never fail the build unless you set `failOnError: true`: the
+plugin logs them. Maps you configured are kept, so you can upload them later
+with `monocle sourcemaps upload <directory>`. Watch builds are skipped.
+
+Matching uses debug IDs, never file names or releases, so the same file
+uploaded twice is stored once and redeploys stay resolvable.

package/dist/vite.d.mts

@@ -23,6 +23,36 @@ interface MonoclePluginOptions {
    * Log the detected release and where it came from.
    */
   verbose?: boolean;
+  /**
+   * Give production bundles debug IDs and upload their source maps to Monocle, so stack traces
+   * show your original code. Enabled by default for builds; pass `false` to turn it off.
+   */
+  sourcemaps?: false | MonocleSourcemapsOptions;
+}
+interface MonocleSourcemapsOptions {
+  /**
+   * Monocle API key used to upload. Defaults to `MONOCLE_API_KEY`. Without a key, the plugin
+   * does not turn source maps on, and only injects debug IDs into maps you configured.
+   */
+  apiKey?: string;
+  /**
+   * Defaults to `https://api.monocle.sh`.
+   */
+  apiUrl?: string;
+  /**
+   * Release shown next to the uploaded files. Defaults to the detected release.
+   */
+  release?: string;
+  /**
+   * Source maps the plugin turned on itself (`build.sourcemap` not configured) are deleted
+   * once processed, even when the upload fails, unless this is `false`. Maps you configured are
+   * kept, unless this is `true`: they are then deleted after a successful upload.
+   */
+  deleteAfterUpload?: boolean;
+  /**
+   * Fail the build when injection or upload fails. Defaults to `false`: errors are logged.
+   */
+  failOnError?: boolean;
 }
 //#endregion
 //#region src/vite.d.ts
@@ -34,7 +64,8 @@ declare class MonocleVitePlugin {
 }
 /**
  * Detect the release at build time and expose it to `@monocle.sh/browser-sdk`, in dev and build.
+ * After each build, give the bundles debug IDs and upload their source maps.
  */
 declare function monocle(options?: MonoclePluginOptions): Plugin;
 //#endregion
-export { type MonoclePluginOptions, MonocleVitePlugin, monocle };
+export { type MonoclePluginOptions, type MonocleSourcemapsOptions, MonocleVitePlugin, monocle };

package/dist/vite.mjs

@@ -1,6 +1,8 @@
-import { readFileSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
+import { readFileSync, statSync } from "node:fs";
 import MagicString from "magic-string";
+import { rm } from "node:fs/promises";
+import { injectDebugIds, uploadSourcemaps } from "@monocle.sh/sourcemaps";
 //#region ../otel-utils/dist/service-version.mjs
 var ServiceVersionDetector = class {
 	/**
@@ -419,6 +421,110 @@ var MonocleBuild = class {
 	}
 };
 //#endregion
+//#region src/core/sourcemaps_step.ts
+/**
+* Inject debug IDs into the written chunks, then upload their source maps when an API key is
+* available. Bundler-agnostic: adapters call `sourcemapDefault` while configuring and `run` once
+* the output is on disk.
+*/
+var SourcemapsStep = class {
+	#options;
+	#enabledHiddenMaps = false;
+	#missingApiKey = false;
+	#processed = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.#options = options;
+	}
+	get #settings() {
+		return this.#options.options.sourcemaps || {};
+	}
+	get #apiKey() {
+		return this.#settings.apiKey ?? this.#options.env?.MONOCLE_API_KEY;
+	}
+	get enabled() {
+		return this.#options.options.enabled !== false && this.#options.options.sourcemaps !== false;
+	}
+	/**
+	* Turn on hidden source maps when the user did not configure them and an API key can upload
+	* them: the maps are generated without a `sourceMappingURL` comment pointing browsers to
+	* them, and deleted once processed.
+	*/
+	sourcemapDefault(configured) {
+		if (!this.enabled || configured !== void 0) return;
+		if (!this.#apiKey) {
+			this.#missingApiKey = true;
+			return;
+		}
+		this.#enabledHiddenMaps = true;
+		return "hidden";
+	}
+	/**
+	* Explain the resolved build configuration: why no source map is generated, or that the
+	* configured ones are referenced by the bundles, so browsers download them.
+	*/
+	checkConfig(options) {
+		if (this.#missingApiKey) options.logger.info("[monocle] Set MONOCLE_API_KEY or sourcemaps.apiKey to generate and upload source maps.");
+		if (this.enabled && options.sourcemap === true) options.logger.warn("[monocle] build.sourcemap is true: browsers can download your source maps. Use 'hidden' to upload them without serving them.");
+	}
+	async #deleteSourcemaps(options) {
+		const count = (await Promise.all(options.paths.map((path) => rm(path).then(() => true, () => false)))).filter(Boolean).length;
+		if (count > 0) options.logger.info(`[monocle] Removed ${count} source map(s) from the output.`);
+	}
+	async #process(options) {
+		const { logger } = options;
+		const settings = this.#settings;
+		const { files } = await injectDebugIds({
+			directory: options.directory,
+			files: options.files
+		});
+		for (const file of files) if (file.status === "invalid_sourcemap") logger.warn(`[monocle] ${file.error}`);
+		const ready = files.filter((file) => file.debugId && file.sourcemap);
+		if (ready.length === 0) return;
+		const apiKey = this.#apiKey;
+		if (!apiKey) {
+			logger.info(`[monocle] Debug IDs injected into ${ready.length} file(s). Set MONOCLE_API_KEY or sourcemaps.apiKey to upload source maps.`);
+			return;
+		}
+		const result = await uploadSourcemaps({
+			directory: options.directory,
+			files: ready.map((file) => file.file),
+			apiKey,
+			apiUrl: settings.apiUrl,
+			release: settings.release ?? options.release,
+			root: options.root,
+			logger: {
+				info: () => {},
+				warn: (message) => logger.warn(`[monocle] ${message}`)
+			}
+		});
+		logger.info(`[monocle] Source maps: ${result.uploaded.length} uploaded, ${result.skipped.length} already uploaded.`);
+		if (!this.#enabledHiddenMaps && settings.deleteAfterUpload) await this.#deleteSourcemaps({
+			paths: ready.map((file) => file.sourcemap),
+			logger
+		});
+	}
+	/**
+	* Process one output directory once. Errors are logged unless `failOnError` is set. The maps
+	* the plugin enabled are deleted even when the upload fails, so they are never deployed.
+	*/
+	async run(options) {
+		if (!this.enabled || this.#processed.has(options.directory)) return;
+		this.#processed.add(options.directory);
+		try {
+			await this.#process(options);
+		} catch (error) {
+			const message = `[monocle] Could not process source maps: ${error.message}`;
+			if (this.#settings.failOnError) throw new Error(message, { cause: error });
+			options.logger.error(message);
+		} finally {
+			if (this.#enabledHiddenMaps && this.#settings.deleteAfterUpload !== false) await this.#deleteSourcemaps({
+				paths: options.files.map((file) => `${file}.map`),
+				logger: options.logger
+			});
+		}
+	}
+};
+//#endregion
 //#region src/vite.ts
 /**
 * Translate Vite hooks to the bundler-agnostic Monocle build.
@@ -428,6 +534,11 @@ var MonocleVitePlugin = class {
 		const plugin = { name: "@monocle.sh/vite-plugin" };
 		if (options.enabled === false) return plugin;
 		let build;
+		let resolved;
+		const sourcemaps = new SourcemapsStep({
+			options,
+			env: process.env
+		});
 		return {
 			...plugin,
 			/**
@@ -435,7 +546,17 @@ var MonocleVitePlugin = class {
 			* JavaScript instead of a raw component, wherever `monocle()` sits in `plugins`.
 			*/
 			enforce: "post",
+			config(config, env) {
+				if (env.command !== "build") return;
+				const sourcemap = sourcemaps.sourcemapDefault(config.build?.sourcemap);
+				if (sourcemap) return { build: { sourcemap } };
+			},
 			configResolved(config) {
+				resolved = config;
+				if (config.command === "build") sourcemaps.checkConfig({
+					sourcemap: config.build.sourcemap,
+					logger: config.logger
+				});
 				build = new MonocleBuild({
 					options,
 					cwd: config.root,
@@ -460,12 +581,37 @@ var MonocleVitePlugin = class {
 						id
 					});
 				}
+			},
+			/**
+			* Sequential and last, so compression or copy plugins see the injected files.
+			*/
+			writeBundle: {
+				sequential: true,
+				order: "post",
+				async handler(output, bundle) {
+					if (!resolved || resolved.command !== "build" || resolved.build.watch) return;
+					if (!resolved.build.sourcemap) return;
+					const directory = resolve(resolved.root, output.dir ?? dirname(output.file ?? "."));
+					const files = Object.values(bundle).filter((item) => item.type === "chunk").map((chunk) => join(directory, chunk.fileName));
+					try {
+						await sourcemaps.run({
+							directory,
+							files,
+							root: resolved.root,
+							release: build?.resolve()?.version,
+							logger: resolved.logger
+						});
+					} catch (error) {
+						this.error(error);
+					}
+				}
 			}
 		};
 	}
 };
 /**
 * Detect the release at build time and expose it to `@monocle.sh/browser-sdk`, in dev and build.
+* After each build, give the bundles debug IDs and upload their source maps.
 */
 function monocle(options = {}) {
 	return MonocleVitePlugin.create(options);

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@monocle.sh/vite-plugin",
-  "version": "0.1.0",
-  "description": "Vite plugin that injects your release into the Monocle Browser SDK at build time",
+  "version": "0.2.1",
+  "description": "Vite plugin that injects your release into the Monocle Browser SDK and uploads source maps at build time",
   "keywords": [
     "monocle",
     "observability",
     "opentelemetry",
     "release",
+    "sourcemaps",
     "vite",
     "vite-plugin"
   ],
@@ -37,7 +38,8 @@
     "tag": "latest"
   },
   "dependencies": {
-    "magic-string": "^0.30.21"
+    "magic-string": "^0.30.21",
+    "@monocle.sh/sourcemaps": "^0.1.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.63.0",
@@ -47,8 +49,8 @@
     "tsdown": "^0.21.10",
     "vite": "^8.3.4",
     "vue": "^3.5.44",
-    "@monocle.sh/browser-sdk": "0.4.0",
-    "@monocle.sh/otel-utils": "1.7.0"
+    "@monocle.sh/browser-sdk": "0.12.0",
+    "@monocle.sh/otel-utils": "1.9.0"
   },
   "peerDependencies": {
     "vite": ">=5.0.0"