vendeps 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alexewerlof
+
+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

@@ -0,0 +1,171 @@
+# vendeps
+
+**One ESM file per dependency, ready for the browser.**
+Vendor your dependencies for added reliability, security and simplicity.
+
+`vendeps` reads the `dependencies` in your `package.json`, uses [esbuild](https://esbuild.github.io/) to bundle each one into a single ESM file, and drops the results into a `dependencies/` folder. Your browser code can then import them with plain `import` statements — no bundler, no build step, no CDN required.
+
+```js
+import { html, render } from './dependencies/lit-html.js'
+import confetti from './dependencies/canvas-confetti.js'
+```
+
+## Why?
+
+Modern browsers support ES modules natively, but most npm packages still ship CommonJS or split their code across dozens of files. Using a CDN solves the format problem but introduces new ones:
+
+- **Security** — Every page load fetches code from a third-party server, opening the door to man-in-the-middle attacks or CDN compromises.
+- **Reliability** — Your app's uptime becomes coupled to the CDN's uptime.
+- **Reproducibility** — CDN URLs can change, disappear, or serve different versions.
+- **Predictability** — You know exactly what code your users are running.
+
+`vendeps` takes a different approach: convert each dependency into a single, self-contained `.js` file that you **check into your repository**. Your app ships everything it needs — no external requests at runtime, no surprises.
+
+## Quick Start
+
+No installation required. In any project that has a `package.json` with `dependencies`:
+
+```bash
+npx vendeps
+```
+
+That's it. A `dependencies/` folder appears with one `.js` file per dependency. Point your `<script type="module">` at them and go.
+
+## Installation
+
+If you prefer to install it as a dev dependency:
+
+```bash
+npm install --save-dev vendeps
+```
+
+### Automate with `postinstall`
+
+To ensure the `dependencies/` folder is always up to date after `npm install` or `npm ci`, add a `postinstall` script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "vendeps --minify"
+  }
+}
+```
+
+Now every `npm ci` on your CI server or a fresh clone will automatically populate the `dependencies/` folder with minified bundles — no extra step to remember.
+
+## CLI Options
+
+```
+npx vendeps [options]
+```
+
+| Option | Description |
+|---|---|
+| `--minify` | Minify the output bundles. Also activates automatically when `NODE_ENV=production`. |
+| `--target <dir>` | Output to `<dir>/` instead of the default `dependencies/`. The directory is created if it doesn't exist. |
+| `--help` | Show usage information and exit. |
+
+### Examples
+
+```bash
+# Bundle everything into dependencies/
+npx vendeps
+
+# Minified production bundles
+npx vendeps --minify
+
+# Output to a custom folder
+npx vendeps --target vendor
+
+# Combine options
+npx vendeps --minify --target lib/vendor
+```
+
+## Per-Dependency Configuration
+
+By default, `vendeps` re-exports everything from each dependency:
+
+```js
+// generated: export * from 'some-package'
+```
+
+You can customize this behavior per-dependency via the `"vendeps"` key in your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "lit-html": "^3.0.0",
+    "chart.js": "^4.0.0",
+    "some-internal-tool": "^1.0.0",
+    "@huggingface/transformers": "^3.0.0"
+  },
+  "vendeps": {
+    "some-internal-tool": null,
+    "chart.js": {
+      "export": "{ Chart }",
+      "define": ["PRODUCTION"]
+    }
+  }
+}
+```
+
+### Config Options
+
+| Config value | Effect |
+|---|---|
+| *(not set)* | Default — `export * from '<packageName>'` |
+| `null` or `false` | **Skip** this dependency entirely. |
+| `"path/to/file.js"` | Use a custom import source instead of the package name. |
+| `{ ... }` | Full configuration object (see below). |
+
+### Full Config Object
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `from` | `string` | package name | The import source path. |
+| `export` | `string` | `"*"` | The export style, e.g. `"*"`, `"{ Chart }"`, `"default"`. |
+| `define` | `object` or `string[]` | `{}` | [esbuild `define`](https://esbuild.github.io/api/#define) replacements. When an array of strings, each is defined as `"true"`. |
+
+### Scoped Packages
+
+Scoped packages like `@huggingface/transformers` are output with their scope directory preserved:
+
+```
+dependencies/@huggingface/transformers.js
+```
+
+Import them the same way:
+
+```js
+import { pipeline } from './dependencies/@huggingface/transformers.js'
+```
+
+## Recommended Workflow
+
+1. **Add your npm dependencies** as usual with `npm install`.
+2. **Run `npx vendeps`** (or let `postinstall` handle it).
+3. **Check in the `dependencies/` folder** to version control.
+4. **Import from `dependencies/`** in your browser JS files.
+
+```
+my-project/
+├── package.json
+├── dependencies/       ← checked into git
+│   ├── lit-html.js
+│   ├── canvas-confetti.js
+│   └── @huggingface/
+│       └── transformers.js
+├── index.html
+└── app.js              ← import from ./dependencies/
+```
+
+By committing the `dependencies/` folder, you get:
+
+- **Self-contained deployments** — no install step needed on the server, no external fetches at runtime.
+- **No CDN dependency** — your app works even if every CDN on the internet goes down.
+- **Auditability** — the exact code your users receive is visible in your repo.
+- **Reproducibility** — every clone, every checkout, every deploy uses the exact same dependency code.
+
+## License
+
+[MIT](LICENSE)

package/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { mkdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import * as esbuild from 'esbuild'
+import { toEsbuildOptionsArr } from './parser.js'
+
+const CONFIG_KEY = 'vendeps'
+const DEFAULT_TARGET_DIR = 'dependencies'
+
+function getTarget(argv) {
+    const i = argv.indexOf('--target')
+    return i !== -1 && argv[i + 1] ? argv[i + 1] : DEFAULT_TARGET_DIR
+}
+
+const targetDir = getTarget(process.argv)
+
+if (process.argv.includes('--help')) {
+    console.log([
+        'vendeps — Convert npm dependencies to ESM bundles ready for the browser environment.',
+        '',
+        'Usage: npx vendeps [options]',
+        '',
+        'Options:',
+        `  --target <dir>  Output directory (default: "${DEFAULT_TARGET_DIR}")`,
+        '  --minify        Minify the output bundles (default: false, also activates when NODE_ENV=production)',
+        '  --help          Show this help message',
+        '',
+        'Reads "dependencies" from package.json and bundles each one into <target>/<name>.js.',
+        'Per-dependency config can be set via the "vendeps" key in package.json.',
+        '',
+        'Scoped packages (e.g. @huggingface/transformers) are output as <target>/@scope/<name>.js.',
+    ].join('\n'))
+    process.exit(0)
+}
+
+async function getDependenciesAndConfig(path) {
+    const { dependencies, [CONFIG_KEY]: vendepsConfig } = JSON.parse(await readFile(path, 'utf-8'))
+    return { dependencies, vendepsConfig }
+}
+
+async function readConfig(resolveDir, minify) {
+    const { dependencies, vendepsConfig } = await getDependenciesAndConfig(join(resolveDir, 'package.json'))
+    return toEsbuildOptionsArr(Object.keys(dependencies), vendepsConfig, resolveDir, minify, targetDir).filter(Boolean)
+}
+
+async function main() {
+    const minify = process.argv.includes('--minify') || process.env.NODE_ENV === 'production'
+
+    console.time('Read config')
+    const optionsArr = await readConfig(process.cwd(), minify)
+    console.timeEnd('Read config')
+    if (optionsArr.length === 0) {
+        console.info('🫙 No dependencies to process. Exiting.')
+        process.exit(0)
+    }
+
+    await mkdir(targetDir, { recursive: true });
+    console.info(`🏃 Updating ${targetDir} for ${optionsArr.length} dependency(ies). Minify: ${minify}`)
+
+    console.time('Build')
+    await Promise.all(optionsArr.map((options) => esbuild.build(options)))
+    console.timeEnd('Build')
+    console.log(`🎉 Updated ${targetDir} dir.`)
+}
+
+main().catch((err) => {
+    console.error(`❌ ${err}`)
+    process.exitCode = 1
+})

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "vendeps",
+  "version": "1.0.0",
+  "description": "Uses esbuild to convert npm packages to ESM bundles for the browser.",
+  "main": "index.js",
+  "bin": {
+    "vendeps": "index.js"
+  },
+  "files": [
+    "index.js",
+    "parser.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "esm",
+    "esbuild",
+    "bundle",
+    "browser",
+    "dependencies",
+    "modules",
+    "import",
+    "cdn-alternative"
+  ],
+  "author": "alexewerlof",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexewerlof/vendeps.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alexewerlof/vendeps/issues"
+  },
+  "homepage": "https://github.com/alexewerlof/vendeps#readme",
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "esbuild": "^0.27.3",
+    "jty": "^4.0.0"
+  }
+}

package/parser.js

@@ -0,0 +1,117 @@
+import { isArr, isBool, isObj, isStr } from "jty"
+import { join } from "node:path"
+const skipConfig = [null, false]
+
+function configObj(frm, exp = '*', def = {}) {
+    if (!isStr(frm)) {
+        throw new TypeError(`'from' must be a string. Got ${frm} (${typeof frm})`)
+    }
+    if (frm.length === 0) {
+        throw new RangeError(`'from' cannot be an empty string.`)
+    }
+    // Name cannot contain quotation marks ' or ", as they would break the generated code.
+    if (frm.includes('"') || frm.includes("'")) {
+        throw new SyntaxError(`'from' cannot contain quotation marks. Got ${frm}`)
+    }
+
+    if (!isStr(exp)) {
+        throw new TypeError(`'export' should be a string. Got ${exp} (${typeof exp}).`)
+    }
+    if (exp.length === 0) {
+        throw new RangeError(`'export' cannot be an empty string.`)
+    }
+
+    if (!isObj(def)) {
+        throw new TypeError(`'define' should be an object. Got ${def} (${typeof def}).`)
+    }
+    if (Array.isArray(def)) {
+        const arr = def
+        def = {}
+
+        for (let i = 0; i < arr.length; i++) {
+            const item = arr[i]
+            if (!isStr(item)) {
+                throw new TypeError(`When 'define' is an array, all items should be strings. Got ${item} (${typeof item}) at index ${i}.`)
+            }
+            def[item] = String(true)
+        }
+    }
+
+    const ret = {
+        contents: `export ${exp} from '${frm}'`,
+        define: def || {},
+    }
+    return ret
+}
+
+function normalizedConfig(name, config) {
+    switch (typeof config) {
+        case 'undefined':
+            return configObj(name)
+        case 'string':
+            return configObj(config)
+        case 'object':
+            if (config === null) {
+                throw new TypeError(`When specified, config should be a string or object, got null.`)
+            }
+            if (Array.isArray(config)) {
+                throw new TypeError(`When specified, config should be a string or object, got array.`)
+            }
+            const { export: exp, from: frm = name, define: def } = config
+            return configObj(frm, exp, def)
+        default:
+            throw new TypeError(`When specified, config should be a string or object, got ${typeof config}.`)
+    }
+}
+
+function toEsbuildOptions(name, config, resolveDir, minify, outfile) {
+    const { contents, define } = normalizedConfig(name, config)
+    console.log(`${name}: ${contents}`)
+    return {
+        bundle: true,
+        minify,
+        format: 'esm',
+        define,
+        stdin: {
+            contents,
+            resolveDir,
+            loader: 'js',
+        },
+        outfile,
+    }
+}
+
+export const _test = {
+    configObj,
+    normalizedConfig,
+    toEsbuildOptions,
+}
+
+export function toEsbuildOptionsArr(names, vendepsConfig = {}, resolveDir, minify, targetDir) {
+    if (!isArr(names)) {
+        throw new TypeError(`Expected an array of names. Got ${names} (${typeof names}).`)
+    }
+    if (!isStr(resolveDir)) {
+        throw new TypeError(`Expected 'resolveDir' to be a string. Got ${resolveDir} (${typeof resolveDir}).`)
+    }
+    if (!isBool(minify)) {
+        throw new TypeError(`Expected 'minify' to be a boolean. Got ${minify} (${typeof minify}).`)
+    }
+    if (!isStr(targetDir)) {
+        throw new TypeError(`Expected 'targetDir' to be a string. Got ${targetDir} (${typeof targetDir}).`)
+    }
+
+    return names.map((name) => {
+        const config = vendepsConfig?.[name];
+        if (skipConfig.includes(config)) {
+            console.warn(`Skipping ${name} as its config is ${config}.`)
+            return null
+        }
+        try {
+            return toEsbuildOptions(name, config, resolveDir, minify, join(targetDir, `${name}.js`))
+        } catch (err) {
+            err.message = `Processing config for ${name}: ${err.message}`
+            throw err
+        }
+    })
+}