@b9g/libuild 0.1.0

package/README.md

@@ -0,0 +1,266 @@
+# libuild
+
+Zero-config library builds with ESBuild.
+
+## Installation
+
+```bash
+npm install -D @b9g/libuild
+bun add -d @b9g/libuild
+```
+
+## Usage
+
+```bash
+# Build your library (development mode - no package.json changes)
+libuild build
+
+# Build and update package.json for npm link
+libuild build --save
+
+# Build and publish to npm
+libuild publish
+```
+
+## Features
+
+- **Zero configuration** - Works out of the box
+- **Structure-preserving builds** - Maintains src/ directory structure in dist/
+- **Multiple formats** - ESM, CommonJS, and TypeScript declarations
+- **Universal compatibility** - No runtime requirements (Node.js, Bun, Deno)
+- **Smart entry detection** - Automatically finds all library entry points
+- **Development-friendly** - Optional --save flag prevents git noise during development
+- **Perfect npm link** - Works from both project root and dist directory
+- **UMD builds** - Optional browser-compatible builds
+- **Clean output** - Optimized package.json for consumers
+
+## Conventions
+
+### Entry Points
+- **Library modules**: All top-level `.ts`/`.js` files in `src/` (excluding `_` prefixed files)
+- **CLI binaries**: Any file referenced in `package.json` `bin` field gets compiled to standalone executable
+- **UMD builds**: If `src/umd.ts` exists, creates browser-compatible UMD build
+
+### Output Structure
+- **Structure-preserving**: `src/index.ts` → `dist/src/index.js` (maintains src/ directory)
+- **ESM**: `.js` files with ES module syntax
+- **CommonJS**: `.cjs` files for Node.js compatibility
+- **TypeScript**: `.d.ts` declaration files (when TypeScript is available)
+- **Clean package.json**: Optimized for consumers (no dev scripts)
+
+### Format Control
+- **ESM-only**: Remove the `main` field from package.json to skip CommonJS builds
+- **CommonJS detection**: Presence of `main` field enables `.cjs` builds
+- **UMD builds**: Add `src/umd.ts` for browser-compatible builds
+
+### Export Aliases
+- **Legacy support**: `./index.js` automatically aliases to `./index`
+- **JSX runtime**: `src/jsx-runtime.ts` auto-creates `./jsx-dev-runtime` alias
+- **Package.json**: Always exported as `./package.json`
+- **Custom exports**: Existing exports in package.json are preserved and enhanced
+
+### Package.json Transformations
+- **Development mode** (default): Root package.json unchanged, no git noise
+- **--save mode**: Root package.json updated to point to `./dist/src/*` artifacts for npm link
+- **Dist package.json**: Clean consumer-ready version with relative `src/` paths
+- **Bin paths**: Automatically transformed from `src/` references to built artifacts
+- **Exports field**: Generated for all entry points with proper types-first ordering
+
+## Examples
+
+### Simple Library
+
+Given this structure:
+```
+src/
+  index.ts
+  utils.ts
+  _internal.ts  # ignored (underscore prefix)
+```
+
+Produces:
+```
+dist/
+  src/
+    index.js       # ESM
+    index.cjs      # CommonJS
+    index.d.ts     # TypeScript declarations
+    utils.js
+    utils.cjs
+    utils.d.ts
+  package.json     # Clean consumer version
+```
+
+### Library with CLI
+
+```
+package.json:
+{
+  "bin": { "mytool": "src/cli.js" }
+}
+
+src/
+  index.ts
+  cli.ts
+```
+
+Produces:
+```
+dist/
+  src/
+    index.js
+    index.cjs
+    index.d.ts
+    cli.js         # Compiled CLI
+    cli.cjs
+    cli.d.ts
+  package.json     # bin: { "mytool": "./src/cli.js" }
+```
+
+### ESM-Only Library
+
+To build only ESM (no CommonJS), remove the `main` field:
+
+```json
+// package.json
+{
+  "name": "my-lib",
+  "module": "dist/src/index.js",  // ESM entry
+  "types": "dist/src/index.d.ts"
+  // no "main" field = no CJS
+}
+```
+
+Produces:
+```
+dist/
+  src/
+    index.js       # ESM only
+    index.d.ts
+    utils.js       # ESM only
+    utils.d.ts
+  package.json     # ESM-only exports
+```
+
+### Multi-Format with UMD
+
+```
+src/
+  index.ts
+  utils.ts
+  umd.ts         # Browser build entry
+```
+
+Produces:
+```
+dist/
+  src/
+    index.js
+    index.cjs
+    index.d.ts
+    utils.js
+    utils.cjs
+    utils.d.ts
+    umd.js         # UMD browser build
+  package.json
+```
+
+### Generated Package.json Exports
+
+**Dual format** (ESM + CommonJS):
+```json
+{
+  "main": "src/index.cjs",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    },
+    "./utils": {
+      "types": "./src/utils.d.ts",
+      "import": "./src/utils.js",
+      "require": "./src/utils.cjs"
+    },
+    "./utils.js": {
+      "types": "./src/utils.d.ts",
+      "import": "./src/utils.js",
+      "require": "./src/utils.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+}
+```
+
+**ESM-only** (no `main` field in source):
+```json
+{
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./utils": {
+      "types": "./src/utils.d.ts",
+      "import": "./src/utils.js"
+    },
+    "./utils.js": {
+      "types": "./src/utils.d.ts",
+      "import": "./src/utils.js"
+    },
+    "./package.json": "./package.json"
+  }
+}
+```
+
+**Root package.json** (with --save):
+```json
+{
+  "main": "./dist/src/index.cjs",
+  "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "require": "./dist/src/index.cjs"
+    }
+  }
+}
+```
+
+## Commands
+
+### `libuild build` (default)
+Builds your library in development mode:
+- Compiles all entry points to multiple formats
+- Generates TypeScript declarations
+- Creates optimized package.json files
+- Preserves root package.json (no git noise)
+
+### `libuild build --save`
+Builds and updates root package.json for npm link:
+- Everything from `libuild build`
+- Updates root package.json to point to dist artifacts
+- Perfect for testing with `npm link`
+
+### `libuild publish`
+Builds and publishes to npm:
+- Runs full build with --save
+- Warns if root package.json is not private
+- Publishes from dist directory with clean package.json
+
+## Requirements
+
+- **Node.js 16+** or **Bun 1.0+** (for running libuild)
+- **TypeScript** (optional, for .d.ts generation)
+- No runtime requirements for library consumers
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@b9g/libuild",
+  "version": "0.1.0",
+  "description": "Zero-config library builds",
+  "keywords": [
+    "build",
+    "library",
+    "bundler",
+    "bun",
+    "zero-config",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bikeshaving/libuild.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bikeshaving/libuild/issues"
+  },
+  "bin": {
+    "libuild": "./src/cli.js"
+  },
+  "dependencies": {
+    "esbuild": "^0.19.0",
+    "magic-string": "^0.30.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "type": "module",
+  "types": "src/libuild.d.ts",
+  "files": [
+    "README.md",
+    "src/"
+  ],
+  "main": "src/libuild.cjs",
+  "module": "src/libuild.js",
+  "exports": {
+    ".": {
+      "types": "./src/libuild.d.ts",
+      "import": "./src/libuild.js",
+      "require": "./src/libuild.cjs"
+    },
+    "./cli": {
+      "types": "./src/cli.d.ts",
+      "import": "./src/cli.js",
+      "require": "./src/cli.cjs"
+    },
+    "./cli.js": {
+      "types": "./src/cli.d.ts",
+      "import": "./src/cli.js",
+      "require": "./src/cli.cjs"
+    },
+    "./libuild": {
+      "types": "./src/libuild.d.ts",
+      "import": "./src/libuild.js",
+      "require": "./src/libuild.cjs"
+    },
+    "./libuild.js": {
+      "types": "./src/libuild.d.ts",
+      "import": "./src/libuild.js",
+      "require": "./src/libuild.cjs"
+    },
+    "./umd-plugin": {
+      "types": "./src/umd-plugin.d.ts",
+      "import": "./src/umd-plugin.js",
+      "require": "./src/umd-plugin.cjs"
+    },
+    "./umd-plugin.js": {
+      "types": "./src/umd-plugin.d.ts",
+      "import": "./src/umd-plugin.js",
+      "require": "./src/umd-plugin.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+}

package/src/chunk-EVLPGECD.js

@@ -0,0 +1,71 @@
+// src/umd-plugin.ts
+import * as FS from "fs/promises";
+import * as Path from "path";
+import MagicString from "magic-string";
+function umdPlugin(options) {
+  return {
+    name: "umd-wrapper",
+    setup(build) {
+      build.onEnd(async (result) => {
+        if (result.errors.length > 0)
+          return;
+        const outputDir = build.initialOptions.outdir;
+        if (outputDir) {
+          const files = await FS.readdir(outputDir);
+          for (const file of files) {
+            if (file.endsWith(".js") && !file.endsWith(".js.map")) {
+              await wrapWithUmd(Path.join(outputDir, file), options.globalName);
+            }
+          }
+        }
+      });
+    }
+  };
+}
+async function wrapWithUmd(filePath, globalName) {
+  const code = await FS.readFile(filePath, "utf-8");
+  const ms = new MagicString(code);
+  const sourcemapComment = code.match(/\/\/# sourceMappingURL=.+$/m);
+  if (sourcemapComment) {
+    const index = code.lastIndexOf(sourcemapComment[0]);
+    ms.remove(index, index + sourcemapComment[0].length);
+  }
+  const exportsMatch = code.match(/\nmodule\.exports\s*=\s*([^;]+);?\s*$/);
+  if (exportsMatch) {
+    const index = code.lastIndexOf(exportsMatch[0]);
+    ms.overwrite(index, index + exportsMatch[0].length, `
+return ${exportsMatch[1]};`);
+  }
+  const umdHeader = `(function (root, factory) {
+  if (typeof define === 'function' && define.amd) {
+    // AMD
+    define([], factory);
+  } else if (typeof module === 'object' && module.exports) {
+    // CommonJS
+    module.exports = factory();
+  } else {
+    // Browser globals
+    root.${globalName} = factory();
+  }
+}(typeof self !== 'undefined' ? self : this, function () {
+`;
+  const umdFooter = `
+}));`;
+  ms.prepend(umdHeader);
+  ms.append(umdFooter);
+  const result = ms.toString();
+  const map = ms.generateMap({
+    file: Path.basename(filePath),
+    source: Path.basename(filePath).replace(".js", ".ts"),
+    includeContent: true
+  });
+  await FS.writeFile(filePath, result);
+  await FS.writeFile(filePath + ".map", map.toString());
+  await FS.writeFile(filePath, result + `
+//# sourceMappingURL=${Path.basename(filePath)}.map`);
+}
+
+export {
+  umdPlugin
+};
+//# sourceMappingURL=chunk-EVLPGECD.js.map

package/src/chunk-EVLPGECD.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/umd-plugin.ts"],
+  "sourcesContent": ["import * as FS from \"fs/promises\";\nimport * as Path from \"path\";\nimport MagicString from \"magic-string\";\n\ninterface UmdPluginOptions {\n  globalName: string;\n}\n\nexport function umdPlugin(options: UmdPluginOptions) {\n  return {\n    name: \"umd-wrapper\",\n    setup(build: any) {\n      build.onEnd(async (result: any) => {\n        if (result.errors.length > 0) return;\n\n        // ESBuild doesn't provide outputFiles by default unless write: false\n        // We need to find the generated files in the output directory\n        const outputDir = build.initialOptions.outdir;\n        if (outputDir) {\n          const files = await FS.readdir(outputDir);\n          for (const file of files) {\n            if (file.endsWith(\".js\") && !file.endsWith(\".js.map\")) {\n              await wrapWithUmd(Path.join(outputDir, file), options.globalName);\n            }\n          }\n        }\n      });\n    },\n  };\n}\n\nasync function wrapWithUmd(filePath: string, globalName: string) {\n  const code = await FS.readFile(filePath, \"utf-8\");\n  const ms = new MagicString(code);\n\n  // Remove sourcemap comment\n  const sourcemapComment = code.match(/\\/\\/# sourceMappingURL=.+$/m);\n  if (sourcemapComment) {\n    const index = code.lastIndexOf(sourcemapComment[0]);\n    ms.remove(index, index + sourcemapComment[0].length);\n  }\n\n  // Replace module.exports with return\n  const exportsMatch = code.match(/\\nmodule\\.exports\\s*=\\s*([^;]+);?\\s*$/);\n  if (exportsMatch) {\n    const index = code.lastIndexOf(exportsMatch[0]);\n    ms.overwrite(index, index + exportsMatch[0].length, `\\nreturn ${exportsMatch[1]};`);\n  }\n\n  // UMD wrapper\n  const umdHeader = `(function (root, factory) {\n  if (typeof define === 'function' && define.amd) {\n    // AMD\n    define([], factory);\n  } else if (typeof module === 'object' && module.exports) {\n    // CommonJS\n    module.exports = factory();\n  } else {\n    // Browser globals\n    root.${globalName} = factory();\n  }\n}(typeof self !== 'undefined' ? self : this, function () {\n`;\n\n  const umdFooter = `\n}));`;\n\n  // Wrap with UMD\n  ms.prepend(umdHeader);\n  ms.append(umdFooter);\n\n  // Generate sourcemap and write files\n  const result = ms.toString();\n  const map = ms.generateMap({\n    file: Path.basename(filePath),\n    source: Path.basename(filePath).replace(\".js\", \".ts\"),\n    includeContent: true,\n  });\n\n  await FS.writeFile(filePath, result);\n  await FS.writeFile(filePath + \".map\", map.toString());\n  await FS.writeFile(filePath, result + `\\n//# sourceMappingURL=${Path.basename(filePath)}.map`);\n}\n"],
+  "mappings": ";AAAA,YAAY,QAAQ;AACpB,YAAY,UAAU;AACtB,OAAO,iBAAiB;AAMjB,SAAS,UAAU,SAA2B;AACnD,SAAO;AAAA,IACL,MAAM;AAAA,IACN,MAAM,OAAY;AAChB,YAAM,MAAM,OAAO,WAAgB;AACjC,YAAI,OAAO,OAAO,SAAS;AAAG;AAI9B,cAAM,YAAY,MAAM,eAAe;AACvC,YAAI,WAAW;AACb,gBAAM,QAAQ,MAAS,WAAQ,SAAS;AACxC,qBAAW,QAAQ,OAAO;AACxB,gBAAI,KAAK,SAAS,KAAK,KAAK,CAAC,KAAK,SAAS,SAAS,GAAG;AACrD,oBAAM,YAAiB,UAAK,WAAW,IAAI,GAAG,QAAQ,UAAU;AAAA,YAClE;AAAA,UACF;AAAA,QACF;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEA,eAAe,YAAY,UAAkB,YAAoB;AAC/D,QAAM,OAAO,MAAS,YAAS,UAAU,OAAO;AAChD,QAAM,KAAK,IAAI,YAAY,IAAI;AAG/B,QAAM,mBAAmB,KAAK,MAAM,6BAA6B;AACjE,MAAI,kBAAkB;AACpB,UAAM,QAAQ,KAAK,YAAY,iBAAiB,CAAC,CAAC;AAClD,OAAG,OAAO,OAAO,QAAQ,iBAAiB,CAAC,EAAE,MAAM;AAAA,EACrD;AAGA,QAAM,eAAe,KAAK,MAAM,uCAAuC;AACvE,MAAI,cAAc;AAChB,UAAM,QAAQ,KAAK,YAAY,aAAa,CAAC,CAAC;AAC9C,OAAG,UAAU,OAAO,QAAQ,aAAa,CAAC,EAAE,QAAQ;AAAA,SAAY,aAAa,CAAC,CAAC,GAAG;AAAA,EACpF;AAGA,QAAM,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,WAST,UAAU;AAAA;AAAA;AAAA;AAKnB,QAAM,YAAY;AAAA;AAIlB,KAAG,QAAQ,SAAS;AACpB,KAAG,OAAO,SAAS;AAGnB,QAAM,SAAS,GAAG,SAAS;AAC3B,QAAM,MAAM,GAAG,YAAY;AAAA,IACzB,MAAW,cAAS,QAAQ;AAAA,IAC5B,QAAa,cAAS,QAAQ,EAAE,QAAQ,OAAO,KAAK;AAAA,IACpD,gBAAgB;AAAA,EAClB,CAAC;AAED,QAAS,aAAU,UAAU,MAAM;AACnC,QAAS,aAAU,WAAW,QAAQ,IAAI,SAAS,CAAC;AACpD,QAAS,aAAU,UAAU,SAAS;AAAA,uBAA+B,cAAS,QAAQ,CAAC,MAAM;AAC/F;",
+  "names": []
+}