@zharp/esbuild-plugin 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zharp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @zharp/esbuild-plugin
+
+Readable stack traces for an esbuild build in [Zharp](https://zharp.io): it emits external source maps (unless `sourcemap` is set), injects debug IDs into the written JS files and their maps, uploads them, and deletes the maps from the output.
+
+```bash
+npm install --save-dev @zharp/esbuild-plugin
+```
+
+```js
+import * as esbuild from 'esbuild';
+import { zharpEsbuildPlugin } from '@zharp/esbuild-plugin';
+
+await esbuild.build({
+  entryPoints: ['src/app.ts'],
+  bundle: true,
+  minify: true,
+  outdir: 'dist',
+  plugins: [zharpEsbuildPlugin({ app: 42 })],
+});
+```
+
+The plugin turns on `metafile` to know which files the build wrote, and does nothing with `write: false`. It runs on every build; use `disabled` to limit it.
+
+Options: see the [bundler plugins overview](../README.md#options).
+
+MIT © [Zharp](https://zharp.io)

package/dist/index.d.mts

@@ -0,0 +1,28 @@
+import { ZharpPluginOptions } from '@zharp/cli';
+export { ZharpPluginOptions } from '@zharp/cli';
+
+/** The parts of esbuild's plugin API this plugin uses (no dependency on esbuild's types). */
+interface BuildOptions {
+    sourcemap?: boolean | 'linked' | 'inline' | 'external' | 'both';
+    metafile?: boolean;
+    write?: boolean;
+    outdir?: string;
+    outfile?: string;
+    absWorkingDir?: string;
+}
+interface BuildResult {
+    errors: unknown[];
+    metafile?: {
+        outputs: Record<string, unknown>;
+    };
+}
+interface PluginBuild {
+    initialOptions: BuildOptions;
+    onEnd(callback: (result: BuildResult) => void | Promise<void>): void;
+}
+declare function zharpEsbuildPlugin(options?: ZharpPluginOptions): {
+    name: string;
+    setup(build: PluginBuild): void;
+};
+
+export { zharpEsbuildPlugin as default, zharpEsbuildPlugin };

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { ZharpPluginOptions } from '@zharp/cli';
+export { ZharpPluginOptions } from '@zharp/cli';
+
+/** The parts of esbuild's plugin API this plugin uses (no dependency on esbuild's types). */
+interface BuildOptions {
+    sourcemap?: boolean | 'linked' | 'inline' | 'external' | 'both';
+    metafile?: boolean;
+    write?: boolean;
+    outdir?: string;
+    outfile?: string;
+    absWorkingDir?: string;
+}
+interface BuildResult {
+    errors: unknown[];
+    metafile?: {
+        outputs: Record<string, unknown>;
+    };
+}
+interface PluginBuild {
+    initialOptions: BuildOptions;
+    onEnd(callback: (result: BuildResult) => void | Promise<void>): void;
+}
+declare function zharpEsbuildPlugin(options?: ZharpPluginOptions): {
+    name: string;
+    setup(build: PluginBuild): void;
+};
+
+export { zharpEsbuildPlugin as default, zharpEsbuildPlugin };

package/dist/index.js

@@ -0,0 +1,54 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default,
+  zharpEsbuildPlugin: () => zharpEsbuildPlugin
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_path = require("path");
+var import_cli = require("@zharp/cli");
+var JS = /\.(?:js|mjs|cjs)$/;
+function zharpEsbuildPlugin(options = {}) {
+  return {
+    name: "zharp",
+    setup(build) {
+      if (options.disabled) return;
+      const initial = build.initialOptions;
+      if (!initial.sourcemap) initial.sourcemap = "external";
+      initial.metafile = true;
+      const logger = (0, import_cli.pluginLogger)("zharp", options);
+      build.onEnd(async (result) => {
+        if (result.errors.length || initial.write === false || !result.metafile) return;
+        const cwd = initial.absWorkingDir ?? process.cwd();
+        const dir = (0, import_node_path.resolve)(cwd, initial.outdir ?? (initial.outfile ? (0, import_node_path.dirname)(initial.outfile) : "."));
+        const files = Object.keys(result.metafile.outputs).filter((name) => JS.test(name)).map((name) => (0, import_node_path.resolve)(cwd, name));
+        await (0, import_cli.processBuildOutput)(dir, options, { files, logger });
+      });
+    }
+  };
+}
+var index_default = zharpEsbuildPlugin;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  zharpEsbuildPlugin
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\r\n * @zharp/esbuild-plugin: after esbuild writes its output, inject debug IDs into the JS files and\r\n * their source maps, upload them to Zharp, and delete the maps from the output.\r\n *\r\n *     await esbuild.build({ entryPoints: ['src/app.ts'], bundle: true, outdir: 'dist',\r\n *       plugins: [zharpEsbuildPlugin({ app: 42 })] });\r\n */\r\nimport { dirname, resolve } from 'node:path';\r\nimport { pluginLogger, processBuildOutput, type ZharpPluginOptions } from '@zharp/cli';\r\n\r\nexport type { ZharpPluginOptions } from '@zharp/cli';\r\n\r\n/** The parts of esbuild's plugin API this plugin uses (no dependency on esbuild's types). */\r\ninterface BuildOptions {\r\n  sourcemap?: boolean | 'linked' | 'inline' | 'external' | 'both';\r\n  metafile?: boolean;\r\n  write?: boolean;\r\n  outdir?: string;\r\n  outfile?: string;\r\n  absWorkingDir?: string;\r\n}\r\ninterface BuildResult {\r\n  errors: unknown[];\r\n  metafile?: { outputs: Record<string, unknown> };\r\n}\r\ninterface PluginBuild {\r\n  initialOptions: BuildOptions;\r\n  onEnd(callback: (result: BuildResult) => void | Promise<void>): void;\r\n}\r\n\r\nconst JS = /\\.(?:js|mjs|cjs)$/;\r\n\r\nexport function zharpEsbuildPlugin(options: ZharpPluginOptions = {}) {\r\n  return {\r\n    name: 'zharp',\r\n    setup(build: PluginBuild): void {\r\n      if (options.disabled) return;\r\n      const initial = build.initialOptions;\r\n      // External maps: written next to the files, not referenced from them.\r\n      if (!initial.sourcemap) initial.sourcemap = 'external';\r\n      // The metafile is how the plugin knows which files this build wrote.\r\n      initial.metafile = true;\r\n      const logger = pluginLogger('zharp', options);\r\n      build.onEnd(async (result) => {\r\n        if (result.errors.length || initial.write === false || !result.metafile) return;\r\n        const cwd = initial.absWorkingDir ?? process.cwd();\r\n        const dir = resolve(cwd, initial.outdir ?? (initial.outfile ? dirname(initial.outfile) : '.'));\r\n        const files = Object.keys(result.metafile.outputs)\r\n          .filter((name) => JS.test(name))\r\n          .map((name) => resolve(cwd, name));\r\n        await processBuildOutput(dir, options, { files, logger });\r\n      });\r\n    },\r\n  };\r\n}\r\n\r\nexport default zharpEsbuildPlugin;\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,uBAAiC;AACjC,iBAA0E;AAsB1E,IAAM,KAAK;AAEJ,SAAS,mBAAmB,UAA8B,CAAC,GAAG;AACnE,SAAO;AAAA,IACL,MAAM;AAAA,IACN,MAAM,OAA0B;AAC9B,UAAI,QAAQ,SAAU;AACtB,YAAM,UAAU,MAAM;AAEtB,UAAI,CAAC,QAAQ,UAAW,SAAQ,YAAY;AAE5C,cAAQ,WAAW;AACnB,YAAM,aAAS,yBAAa,SAAS,OAAO;AAC5C,YAAM,MAAM,OAAO,WAAW;AAC5B,YAAI,OAAO,OAAO,UAAU,QAAQ,UAAU,SAAS,CAAC,OAAO,SAAU;AACzE,cAAM,MAAM,QAAQ,iBAAiB,QAAQ,IAAI;AACjD,cAAM,UAAM,0BAAQ,KAAK,QAAQ,WAAW,QAAQ,cAAU,0BAAQ,QAAQ,OAAO,IAAI,IAAI;AAC7F,cAAM,QAAQ,OAAO,KAAK,OAAO,SAAS,OAAO,EAC9C,OAAO,CAAC,SAAS,GAAG,KAAK,IAAI,CAAC,EAC9B,IAAI,CAAC,aAAS,0BAAQ,KAAK,IAAI,CAAC;AACnC,kBAAM,+BAAmB,KAAK,SAAS,EAAE,OAAO,OAAO,CAAC;AAAA,MAC1D,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEA,IAAO,gBAAQ;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,29 @@
+// src/index.ts
+import { dirname, resolve } from "path";
+import { pluginLogger, processBuildOutput } from "@zharp/cli";
+var JS = /\.(?:js|mjs|cjs)$/;
+function zharpEsbuildPlugin(options = {}) {
+  return {
+    name: "zharp",
+    setup(build) {
+      if (options.disabled) return;
+      const initial = build.initialOptions;
+      if (!initial.sourcemap) initial.sourcemap = "external";
+      initial.metafile = true;
+      const logger = pluginLogger("zharp", options);
+      build.onEnd(async (result) => {
+        if (result.errors.length || initial.write === false || !result.metafile) return;
+        const cwd = initial.absWorkingDir ?? process.cwd();
+        const dir = resolve(cwd, initial.outdir ?? (initial.outfile ? dirname(initial.outfile) : "."));
+        const files = Object.keys(result.metafile.outputs).filter((name) => JS.test(name)).map((name) => resolve(cwd, name));
+        await processBuildOutput(dir, options, { files, logger });
+      });
+    }
+  };
+}
+var index_default = zharpEsbuildPlugin;
+export {
+  index_default as default,
+  zharpEsbuildPlugin
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\r\n * @zharp/esbuild-plugin: after esbuild writes its output, inject debug IDs into the JS files and\r\n * their source maps, upload them to Zharp, and delete the maps from the output.\r\n *\r\n *     await esbuild.build({ entryPoints: ['src/app.ts'], bundle: true, outdir: 'dist',\r\n *       plugins: [zharpEsbuildPlugin({ app: 42 })] });\r\n */\r\nimport { dirname, resolve } from 'node:path';\r\nimport { pluginLogger, processBuildOutput, type ZharpPluginOptions } from '@zharp/cli';\r\n\r\nexport type { ZharpPluginOptions } from '@zharp/cli';\r\n\r\n/** The parts of esbuild's plugin API this plugin uses (no dependency on esbuild's types). */\r\ninterface BuildOptions {\r\n  sourcemap?: boolean | 'linked' | 'inline' | 'external' | 'both';\r\n  metafile?: boolean;\r\n  write?: boolean;\r\n  outdir?: string;\r\n  outfile?: string;\r\n  absWorkingDir?: string;\r\n}\r\ninterface BuildResult {\r\n  errors: unknown[];\r\n  metafile?: { outputs: Record<string, unknown> };\r\n}\r\ninterface PluginBuild {\r\n  initialOptions: BuildOptions;\r\n  onEnd(callback: (result: BuildResult) => void | Promise<void>): void;\r\n}\r\n\r\nconst JS = /\\.(?:js|mjs|cjs)$/;\r\n\r\nexport function zharpEsbuildPlugin(options: ZharpPluginOptions = {}) {\r\n  return {\r\n    name: 'zharp',\r\n    setup(build: PluginBuild): void {\r\n      if (options.disabled) return;\r\n      const initial = build.initialOptions;\r\n      // External maps: written next to the files, not referenced from them.\r\n      if (!initial.sourcemap) initial.sourcemap = 'external';\r\n      // The metafile is how the plugin knows which files this build wrote.\r\n      initial.metafile = true;\r\n      const logger = pluginLogger('zharp', options);\r\n      build.onEnd(async (result) => {\r\n        if (result.errors.length || initial.write === false || !result.metafile) return;\r\n        const cwd = initial.absWorkingDir ?? process.cwd();\r\n        const dir = resolve(cwd, initial.outdir ?? (initial.outfile ? dirname(initial.outfile) : '.'));\r\n        const files = Object.keys(result.metafile.outputs)\r\n          .filter((name) => JS.test(name))\r\n          .map((name) => resolve(cwd, name));\r\n        await processBuildOutput(dir, options, { files, logger });\r\n      });\r\n    },\r\n  };\r\n}\r\n\r\nexport default zharpEsbuildPlugin;\r\n"],"mappings":";AAOA,SAAS,SAAS,eAAe;AACjC,SAAS,cAAc,0BAAmD;AAsB1E,IAAM,KAAK;AAEJ,SAAS,mBAAmB,UAA8B,CAAC,GAAG;AACnE,SAAO;AAAA,IACL,MAAM;AAAA,IACN,MAAM,OAA0B;AAC9B,UAAI,QAAQ,SAAU;AACtB,YAAM,UAAU,MAAM;AAEtB,UAAI,CAAC,QAAQ,UAAW,SAAQ,YAAY;AAE5C,cAAQ,WAAW;AACnB,YAAM,SAAS,aAAa,SAAS,OAAO;AAC5C,YAAM,MAAM,OAAO,WAAW;AAC5B,YAAI,OAAO,OAAO,UAAU,QAAQ,UAAU,SAAS,CAAC,OAAO,SAAU;AACzE,cAAM,MAAM,QAAQ,iBAAiB,QAAQ,IAAI;AACjD,cAAM,MAAM,QAAQ,KAAK,QAAQ,WAAW,QAAQ,UAAU,QAAQ,QAAQ,OAAO,IAAI,IAAI;AAC7F,cAAM,QAAQ,OAAO,KAAK,OAAO,SAAS,OAAO,EAC9C,OAAO,CAAC,SAAS,GAAG,KAAK,IAAI,CAAC,EAC9B,IAAI,CAAC,SAAS,QAAQ,KAAK,IAAI,CAAC;AACnC,cAAM,mBAAmB,KAAK,SAAS,EAAE,OAAO,OAAO,CAAC;AAAA,MAC1D,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEA,IAAO,gBAAQ;","names":[]}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@zharp/esbuild-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Zharp esbuild plugin: inject debug IDs and upload source maps",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "keywords": [
+    "zharp",
+    "sourcemaps",
+    "debug-id",
+    "error-tracking",
+    "esbuild",
+    "esbuild-plugin"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zharp-io/zharp-javascript-lib.git",
+    "directory": "packages/bundler-plugins/esbuild"
+  },
+  "homepage": "https://zharp.io/docs/sourcemaps",
+  "bugs": "https://github.com/zharp-io/zharp-javascript-lib/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zharp/cli": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
 }