Ship ESM and CommonJS builds so packages are importable by bundlers

.changeset/esm-module-exports.md

@@ -0,0 +1,10 @@
+---
+"@matdata/yasgui-utils": minor
+"@matdata/yasqe": minor
+"@matdata/yasr": minor
+"@matdata/yasgui": minor
+---
+
+Ship ES module and CommonJS builds so the packages can be imported by bundlers (Vite/webpack/esbuild) and Node.
+
+Each package now builds three bundles: an ES module (`*.mjs`), a CommonJS module (`*.cjs`) and the existing browser global IIFE (`*.min.js`). The `package.json` of every package exposes them through `main` (CommonJS), `module` (ESM), `unpkg`/`jsdelivr` (browser global) and a conditional `exports` map with `import`, `require`, `types` and `default` entries. This makes the documented `import Yasgui from "@matdata/yasgui"` usage work in module bundlers, while `<script src=".../build/yasgui.min.js">` keeps exposing the global.

docs/developer-guide.md

@@ -452,7 +452,7 @@ const yasgui = new Yasgui(document.getElementById('yasgui'), {
 ### CommonJS
 
 ```javascript
-const Yasgui = require('@matdata/yasgui');
+const Yasgui = require('@matdata/yasgui').default;
 require('@matdata/yasgui/build/yasgui.min.css');
 
 const yasgui = new Yasgui(document.getElementById('yasgui'));

esbuild.config.js

@@ -93,8 +93,41 @@ const commonConfig = {
   },
 };
 
+// Rename the CSS output emitted by a build to the canonical `<name>.min.css`.
+function extractCss(result, name) {
+  if (!result.metafile) return;
+  const cssOutput = Object.keys(result.metafile.outputs).find((o) => o.endsWith(".css"));
+  if (!cssOutput || !fs.existsSync(cssOutput)) return;
+
+  const targetCss = `build/${name}.min.css`;
+  const sourceMap = `${cssOutput}.map`;
+  const targetMap = `${targetCss}.map`;
+
+  if (cssOutput !== targetCss) {
+    fs.renameSync(cssOutput, targetCss);
+    if (fs.existsSync(sourceMap)) fs.renameSync(sourceMap, targetMap);
+
+    // Keep the sourcemap reference consistent with the renamed file.
+    const css = fs.readFileSync(targetCss, "utf8");
+    const updated = css.replace(/sourceMappingURL=.*?\*\//, `sourceMappingURL=${path.basename(targetMap)} */`);
+    if (updated !== css) fs.writeFileSync(targetCss, updated);
+  }
+}
+
+// Remove the CSS (and its sourcemap) emitted by a build. The ESM/CJS bundles
+// import the same styles as the IIFE build, so a single `<name>.min.css` is kept.
+function removeExtraCss(result) {
+  if (!result.metafile) return;
+  for (const output of Object.keys(result.metafile.outputs)) {
+    if (output.endsWith(".css") || output.endsWith(".css.map")) {
+      if (fs.existsSync(output)) fs.rmSync(output);
+    }
+  }
+}
+
 async function buildPackage(name, entryPoint, globalName) {
-  const result = await esbuild.build({
+  // IIFE build: exposes a browser global (e.g. `window.Yasgui`) for <script> usage.
+  const iifeResult = await esbuild.build({
     ...commonConfig,
     entryPoints: [entryPoint],
     outfile: `build/${name}.min.js`,
@@ -107,15 +140,31 @@ async function buildPackage(name, entryPoint, globalName) {
       js: `if (typeof ${globalName} !== 'undefined' && ${globalName}?.default) { ${globalName} = ${globalName}.default; }`,
     },
   });
+  extractCss(iifeResult, name);
 
-  // Extract CSS if any was bundled
-  if (result.metafile) {
-    const outputs = Object.keys(result.metafile.outputs);
-    const cssOutput = outputs.find((o) => o.endsWith(".css"));
-    if (cssOutput && fs.existsSync(cssOutput)) {
-      fs.renameSync(cssOutput, `build/${name}.min.css`);
-    }
-  }
+  // ESM build: consumed by bundlers (vite/webpack/esbuild) and Node via `import`.
+  // Uses the `.mjs` extension so it is always treated as an ES module.
+  const esmResult = await esbuild.build({
+    ...commonConfig,
+    entryPoints: [entryPoint],
+    outfile: `build/${name}.mjs`,
+    format: "esm",
+    platform: "browser",
+    metafile: true,
+  });
+  removeExtraCss(esmResult);
+
+  // CJS build: consumed by Node's `require`. Uses the `.cjs` extension so it is
+  // always treated as CommonJS regardless of the nearest package.json `type`.
+  const cjsResult = await esbuild.build({
+    ...commonConfig,
+    entryPoints: [entryPoint],
+    outfile: `build/${name}.cjs`,
+    format: "cjs",
+    platform: "browser",
+    metafile: true,
+  });
+  removeExtraCss(cjsResult);
 }
 
 async function buildTypeDeclarations() {

packages/utils/package.json

@@ -2,8 +2,21 @@
   "name": "@matdata/yasgui-utils",
   "version": "4.6.1",
   "description": "Shared utilities for MatGUI (formerly Yasgui) packages.",
-  "main": "build/utils.min.js",
+  "main": "build/utils.cjs",
+  "module": "build/utils.mjs",
+  "unpkg": "build/utils.min.js",
+  "jsdelivr": "build/utils.min.js",
   "types": "build/ts/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/ts/src/index.d.ts",
+      "import": "./build/utils.mjs",
+      "require": "./build/utils.cjs",
+      "default": "./build/utils.mjs"
+    },
+    "./build/*": "./build/*",
+    "./package.json": "./package.json"
+  },
   "license": "MIT",
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",

packages/yasgui/package.json

@@ -2,8 +2,22 @@
   "name": "@matdata/yasgui",
   "description": "MatGUI: a modern SPARQL query editor and results viewer for knowledge graphs and linked data (formerly Yasgui).",
   "version": "4.6.1",
-  "main": "build/yasgui.min.js",
+  "main": "build/yasgui.cjs",
+  "module": "build/yasgui.mjs",
+  "unpkg": "build/yasgui.min.js",
+  "jsdelivr": "build/yasgui.min.js",
   "types": "build/ts/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/ts/src/index.d.ts",
+      "import": "./build/yasgui.mjs",
+      "require": "./build/yasgui.cjs",
+      "default": "./build/yasgui.mjs"
+    },
+    "./build/yasgui.min.css": "./build/yasgui.min.css",
+    "./build/*": "./build/*",
+    "./package.json": "./package.json"
+  },
   "license": "MIT",
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",

packages/yasqe/package.json

@@ -2,13 +2,27 @@
   "name": "@matdata/yasqe",
   "description": "MatGUI query editor: a modern SPARQL query editor (formerly Yasgui/YASQE).",
   "version": "4.6.1",
-  "main": "build/yasqe.min.js",
+  "main": "build/yasqe.cjs",
+  "module": "build/yasqe.mjs",
+  "unpkg": "build/yasqe.min.js",
+  "jsdelivr": "build/yasqe.min.js",
   "types": "build/ts/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/ts/src/index.d.ts",
+      "import": "./build/yasqe.mjs",
+      "require": "./build/yasqe.cjs",
+      "default": "./build/yasqe.mjs"
+    },
+    "./build/yasqe.min.css": "./build/yasqe.min.css",
+    "./build/*": "./build/*",
+    "./package.json": "./package.json"
+  },
   "license": "MIT",
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",
   "engines": {
-    "node": ">= 8"
+    "node": ">= 12"
   },
   "keywords": [
     "JavaScript",

packages/yasr/package.json

@@ -2,13 +2,27 @@
   "name": "@matdata/yasr",
   "description": "MatGUI results viewer: a modern SPARQL result set viewer (formerly Yasgui/YASR).",
   "version": "4.6.1",
-  "main": "build/yasr.min.js",
+  "main": "build/yasr.cjs",
+  "module": "build/yasr.mjs",
+  "unpkg": "build/yasr.min.js",
+  "jsdelivr": "build/yasr.min.js",
   "types": "build/ts/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/ts/src/index.d.ts",
+      "import": "./build/yasr.mjs",
+      "require": "./build/yasr.cjs",
+      "default": "./build/yasr.mjs"
+    },
+    "./build/yasr.min.css": "./build/yasr.min.css",
+    "./build/*": "./build/*",
+    "./package.json": "./package.json"
+  },
   "license": "MIT",
   "author": "Triply <info@triply.cc>",
   "homepage": "https://github.com/Matdata-eu/Yasgui",
   "engines": {
-    "node": ">= 8"
+    "node": ">= 12"
   },
   "keywords": [
     "JavaScript",