vendeps 1.0.0 → 1.0.2

package/README.md

@@ -14,12 +14,17 @@ import confetti from './dependencies/canvas-confetti.js'
 
 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.
+- **Security** — Every page load fetches code from a third-party server, opening the door to supply-chain, man-in-the-middle, and XSS attacks.
+- **Reliability** — Your app's uptime becomes coupled to the CDN's uptime (and if you depend on multiple CDNs, [it's even worse](https://blog.alexewerlof.com/p/composite-slo)).
 - **Reproducibility** — CDN URLs can change, disappear, or serve different versions.
-- **Predictability** — You know exactly what code your users are running.
+- **Predictability** — You don't always 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.
+`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 to other servers, no surprises.
+
+- **Security** — Vendeps allows you to version-control your dependencies for audit.
+- **Reliability** — Vendeps decouples your app's uptime from external CDNs.
+- **Reproducibility** — Vendeps ensures that your app always uses the same version of a dependency.
+- **Predictability** — Vendeps ensures that the exact same dependency you used during development is used in production.
 
 ## Quick Start
 
@@ -31,7 +36,7 @@ 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
+### npm scripts
 
 If you prefer to install it as a dev dependency:
 
@@ -39,19 +44,55 @@ If you prefer to install it as a dev dependency:
 npm install --save-dev vendeps
 ```
 
-### Automate with `postinstall`
+And then:
 
-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": {
+        "build": "vendeps"
+    }
+}
+```
+
+If you want it to run automatically after `npm install`, you can add a `postinstall` script:
 
 ```json
 {
-  "scripts": {
-    "postinstall": "vendeps --minify"
-  }
+    "scripts": {
+        "postinstall": "vendeps"
+    }
 }
 ```
 
-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.
+⚠️ **Dependency drift** — The vendored bundles are snapshots of whatever versions are installed at build time. If you update a dependency version in `package.json` (or run `npm update`), remember to re-run `npx vendeps` (or trigger a fresh `npm ci`) so the bundles stay in sync. Checking in the `dependencies/` folder helps catch drift — any version bump will show up as a diff in your commit.
+
+ℹ️ **Optional vendor check in** It is recommended to check in the `dependencies/` folder to version control but it's not a requirement for vendeps to work. All it does is to create bundles for your dependencies. So you may as well `.gitignore` the `dependencies/` folder and rely on `postinstall` to create the bundles after `npm install` or `npm ci`.
+
+### Import Maps
+
+Instead of rewriting your imports to point at `./dependencies/**/*.js`, you can use a [browser import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) so your source code keeps using bare specifiers — exactly like Node.js:
+
+```html
+<script type="importmap">
+    {
+        "imports": {
+            "lit-html": "./dependencies/lit-html.js",
+            "canvas-confetti": "./dependencies/canvas-confetti.js"
+        }
+    }
+</script>
+<script type="module" src="app.js"></script>
+```
+
+Now your application code works without any path changes:
+
+```js
+// app.js — same imports you'd write in Node
+import { html, render } from 'lit-html'
+import confetti from 'canvas-confetti'
+```
+
+The browser resolves the bare specifiers through the import map, so your code stays portable between Node.js and the browser with zero modifications.
 
 ## CLI Options
 
@@ -59,11 +100,12 @@ Now every `npm ci` on your CI server or a fresh clone will automatically populat
 npx vendeps [options]
 ```
 
-| Option | Description |
-|---|---|
-| `--minify` | Minify the output bundles. Also activates automatically when `NODE_ENV=production`. |
+| Option           | Description                                                                                              |
+| ---------------- | -------------------------------------------------------------------------------------------------------- |
+| `--minify`       | Minify the output bundles.                                                                               |
 | `--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. |
+| `--src <file>`   | Path to the `package.json` file (defaults to `./package.json`).                                          |
+| `--help`         | Show usage information and exit.                                                                         |
 
 ### Examples
 
@@ -71,7 +113,7 @@ npx vendeps [options]
 # Bundle everything into dependencies/
 npx vendeps
 
-# Minified production bundles
+# Minified bundles
 npx vendeps --minify
 
 # Output to a custom folder
@@ -93,38 +135,40 @@ You can customize this behavior per-dependency via the `"vendeps"` key in your `
 
 ```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"]
+    "dependencies": {
+        "lit-html": "^3.0.0",
+        "chart.js": "^4.0.0",
+        "onnxruntime-node": "1.24.2",
+        "@huggingface/transformers": "^3.0.0"
+    },
+    "vendeps": {
+        // Skip generating bundles for this node-only package in an isomorphic project
+        "onnxruntime-node": null,
+        // Only export Chart from chart.js and define PRODUCTION
+        "chart.js": {
+            "export": "{ Chart }",
+            "define": ["PRODUCTION"]
+        }
     }
-  }
 }
 ```
 
 ### Config Options
 
-| Config value | Effect |
-|---|---|
-| *(not set)* | Default — `export * from '<packageName>'` |
-| `null` or `false` | **Skip** this dependency entirely. |
+| 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 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"`. |
+| 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
 
@@ -166,6 +210,10 @@ By committing the `dependencies/` folder, you get:
 - **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.
 
+## Limitations
+
+> ⚠️ **CSS-only packages** — `vendeps` bundles JavaScript only. If a dependency ships exclusively CSS (e.g. `normalize.css`), it will not be handled. You will need to copy those assets manually or use a separate tool.
+
 ## License
 
 [MIT](LICENSE)

package/index.js

@@ -1,64 +1,82 @@
 #!/usr/bin/env node
+
 import { mkdir, readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { dirname, resolve } from 'node:path'
+import { hideBin } from 'yargs/helpers'
+import yargs from 'yargs'
 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
+async function loadJson(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8')
+        return JSON.parse(content)
+    } catch (err) {
+        throw new Error(`❌ Failed to load JSON from ${filePath}: ${err.message}`)
+    }
 }
 
-const targetDir = getTarget(process.argv)
+import { fileURLToPath } from 'node:url'
+import { packageJsonToEsbuildOptions } from './parser'
 
-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)
-}
+const vendepsPackageJson = await loadJson(resolve(dirname(fileURLToPath(import.meta.url)), 'package.json'))
 
-async function getDependenciesAndConfig(path) {
-    const { dependencies, [CONFIG_KEY]: vendepsConfig } = JSON.parse(await readFile(path, 'utf-8'))
-    return { dependencies, vendepsConfig }
-}
+const CONFIG_KEY = vendepsPackageJson.name
+const DEFAULT_TARGET_DIR = './dependencies'
+const DEFAULT_SRC_FILE = './package.json'
 
-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)
-}
+const argv = yargs(hideBin(process.argv))
+    .usage(`Usage: npx ${vendepsPackageJson.name} [options]`)
+    .option('src', {
+        alias: 's',
+        type: 'string',
+        describe: `Path to the package.json file where dependencies and the optional ${CONFIG_KEY} config are located`,
+        default: DEFAULT_SRC_FILE,
+    })
+    .option('target', {
+        alias: 't',
+        type: 'string',
+        describe: 'Output directory (it will be created if it does not exist)',
+        default: DEFAULT_TARGET_DIR,
+    })
+    .option('minify', {
+        type: 'boolean',
+        describe: 'Minify the output bundles',
+        default: false,
+    })
+    .help('help')
+    .alias('help', 'h')
+    .epilog(vendepsPackageJson.description).argv
+
+const targetDir = resolve(process.cwd(), argv.target)
+const srcFile = resolve(process.cwd(), argv.src)
+const nodeModulesDir = dirname(srcFile)
 
 async function main() {
-    const minify = process.argv.includes('--minify') || process.env.NODE_ENV === 'production'
+    // Only use --minify flag
+    const minify = argv.minify
 
-    console.time('Read config')
-    const optionsArr = await readConfig(process.cwd(), minify)
-    console.timeEnd('Read config')
+    console.time(`Read and parse ${srcFile}`)
+    const optionsArr = await packageJsonToEsbuildOptions(
+        await loadJson(srcFile),
+        CONFIG_KEY,
+        nodeModulesDir,
+        targetDir,
+        minify,
+    )
+    console.timeEnd(`Read and parse ${srcFile}`)
     if (optionsArr.length === 0) {
         console.info('🫙 No dependencies to process. Exiting.')
-        process.exit(0)
+        return
     }
 
-    await mkdir(targetDir, { recursive: true });
+    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)))
+    // await Promise.all(optionsArr.map((options) => esbuild.build(options)))
+    for (const options of optionsArr) {
+        await esbuild.build(options)
+    }
     console.timeEnd('Build')
     console.log(`🎉 Updated ${targetDir} dir.`)
 }

package/package.json

@@ -1,46 +1,52 @@
 {
-  "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"
-  }
-}
+    "name": "vendeps",
+    "version": "1.0.2",
+    "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",
+        "fmt": "prettier --write .",
+        "preversion": "npm run fmt"
+    },
+    "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",
+        "yargs": "^18.0.0"
+    },
+    "devDependencies": {
+        "prettier": "^3.8.1"
+    }
+}

package/parser.js

@@ -1,6 +1,6 @@
-import { isArr, isBool, isObj, isStr } from "jty"
-import { join } from "node:path"
-const skipConfig = [null, false]
+import { isArr, isBool, isObj, isStr } from 'jty'
+import { join } from 'node:path'
+const SKIP_CONFIG_VALUES = [null, false]
 
 function configObj(frm, exp = '*', def = {}) {
     if (!isStr(frm)) {
@@ -31,7 +31,9 @@ function configObj(frm, exp = '*', 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}.`)
+                throw new TypeError(
+                    `When 'define' is an array, all items should be strings. Got ${item} (${typeof item}) at index ${i}.`,
+                )
             }
             def[item] = String(true)
         }
@@ -65,29 +67,28 @@ function normalizedConfig(name, 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,
+    try {
+        const { contents, define } = normalizedConfig(name, config)
+        console.log(`${name}: ${contents}`)
+        return {
+            bundle: true,
+            minify,
+            format: 'esm',
+            define,
+            stdin: {
+                contents,
+                resolveDir,
+                loader: 'js',
+            },
+            outfile,
+        }
+    } catch (err) {
+        err.message = `Error processing config for ${name}: ${err.message}`
+        throw err
     }
 }
 
-export const _test = {
-    configObj,
-    normalizedConfig,
-    toEsbuildOptions,
-}
-
-export function toEsbuildOptionsArr(names, vendepsConfig = {}, resolveDir, minify, targetDir) {
+function toEsbuildOptionsArr(names, vendepsConfig = {}, resolveDir, minify, targetDir) {
     if (!isArr(names)) {
         throw new TypeError(`Expected an array of names. Got ${names} (${typeof names}).`)
     }
@@ -101,17 +102,34 @@ export function toEsbuildOptionsArr(names, vendepsConfig = {}, resolveDir, minif
         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
-        }
-    })
-}
+    return names.map((name) =>
+        toEsbuildOptions(name, vendepsConfig?.[name], resolveDir, minify, join(targetDir, `${name}.js`)),
+    )
+}
+
+export async function packageJsonToEsbuildOptions(packageJson, configKey, resolveDir, targetDir, minify) {
+    if (!isObj(packageJson)) {
+        throw new TypeError(`Invalid package.json object`)
+    }
+    const { dependencies, [configKey]: vendepsConfig } = packageJson
+    if (!isObj(dependencies)) {
+        throw new TypeError(`No 'dependencies' object found`)
+    }
+
+    const dependencyNames = Object.keys(dependencies).filter(
+        (name) => vendepsConfig && !SKIP_CONFIG_VALUES.includes(vendepsConfig?.[name]),
+    )
+
+    if (dependencyNames.length === 0) {
+        throw new Error('No dependencies to process after filtering with config.')
+    }
+
+    return toEsbuildOptionsArr(dependencyNames, vendepsConfig, resolveDir, minify, targetDir).filter(Boolean)
+}
+
+export const _test = {
+    configObj,
+    normalizedConfig,
+    toEsbuildOptions,
+    toEsbuildOptionsArr,
+}