iifeify 1.1.0 → 2.0.0

package/README.md

@@ -3,10 +3,10 @@
 Turn an npm package into one classic browser script.
 
 ```bash
-npx -y iifeify vanilla-jsoneditor@3.13.0 --entry standalone.js --global-name VanillaJsonEditor
+npx -y iifeify vanilla-jsoneditor@3.13.0
 ```
 
-This writes `vanilla-jsoneditor.iife.js`. Loaded with a plain `<script>` tag, the file defines the global `VanillaJsonEditor`, which holds everything the package exports. The file starts with a license banner generated from the package's own metadata:
+This writes `vanilla-jsoneditor.iife.js`. Loaded with a plain `<script>` tag, the file defines the global `VanillaJsonEditor`, which holds everything the package exports. iifeify chose both by itself: the package's browser build `standalone.js`, which needs no other packages, and a global named after the package. The file starts with a license banner generated from the package's own metadata:
 
 ```js
 /*! vanilla-jsoneditor 3.13.0 - Copyright (c) 2020-2026 by Jos de Jong - ISC License - https://github.com/josdejong/svelte-jsoneditor */
@@ -21,6 +21,7 @@ iifeify is for hosts that accept only classic scripts and cannot `import` anythi
 
 - **Any npm package** — installed with npm itself, so versions, ranges, tags, scoped packages, private registries and proxies work as they do for `npm install`
 - **One file, one global** — the package and every dependency it imports, bundled with [esbuild](https://esbuild.github.io/) into an IIFE
+- **No options needed** — the package's own browser build is used when that saves bundling its dependencies, and the global gets the name the package itself uses, holding what its documentation shows
 - **License banner** — one line per bundled package with its version, copyright notice, license and web address, read from its `package.json` and license file
 - **Full license texts** — `--notices` writes the license and notice files of all bundled packages next to the script
 - **Browser check** — a package that imports `fs`, `path` or another Node.js built-in is refused, with the modules and the files that import them
@@ -53,8 +54,8 @@ npx iifeify <package>[@version] [options]
 
 | Option | Meaning | Default |
 | --- | --- | --- |
-| `-e`, `--entry <path>` | File or subpath inside the package to bundle | The package's own browser entry |
-| `-g`, `--global-name <name>` | Global variable the script defines | The package name in PascalCase |
+| `-e`, `--entry <path>` | File or subpath inside the package to bundle | Detected, see [Which file is bundled](#which-file-is-bundled) |
+| `-g`, `--global-name <name>` | Global variable the script defines | Detected, see [The global](#the-global) |
 | `-o`, `--outfile <file>` | Where to write the script | `./<package>.iife.js` |
 | `--no-minify` | Keep the output readable | Minified |
 | `--target <list>` | Language level of the output, for example `es2020` | `esnext` |
@@ -65,42 +66,56 @@ npx iifeify <package>[@version] [options]
 While it runs, iifeify prints each step and how long it took on stderr, and the result on stdout:
 
 ```text
-Installing vanilla-jsoneditor@3.13.0 with npm... done in 3.4s
-Bundling vanilla-jsoneditor 3.13.0 with esbuild... done in 555ms
+Installing vanilla-jsoneditor@3.13.0 with npm... done in 3.3s
+Bundling vanilla-jsoneditor 3.13.0 with esbuild... done in 847ms
 Wrote vanilla-jsoneditor.iife.js (1.21 MB)
   package  vanilla-jsoneditor 3.13.0 - ISC
-  entry    standalone.js
-  global   VanillaJsonEditor
+  entry    standalone.js (browser build without dependencies)
+  global   VanillaJsonEditor (from the package name)
 ```
 
-A step that fails ends with `failed`, followed by the reason. The exit code is 0 on success, 1 if the package cannot be converted and 2 for a wrong command line.
+The summary says which file was bundled and where the global's name comes from. A step that fails ends with `failed`, followed by the reason. The exit code is 0 on success, 1 if the package cannot be converted and 2 for a wrong command line.
 
 ### How it works
 
 1. iifeify runs `npm install` for the package in a temporary folder. It uses your npm configuration, so private registries and proxies work. Install scripts are not run.
-2. It bundles the package and the dependencies it imports into one file with esbuild, in the `iife` format with your global name.
+2. It chooses the file to bundle and the global's name, and bundles that file and the dependencies it imports into one file with esbuild, in the `iife` format.
 3. It reads `package.json` and the license file of every package that ended up in the bundle and writes the banner.
 4. It removes the temporary folder.
 
 ### Which file is bundled
 
-Without `--entry`, iifeify bundles what a bundler picks for an `import` of the package in browser code: the package's `exports` (conditions `browser`, `import`, `module`, `default`), or else its `browser`, `module` or `main` field. Dependencies are bundled from `node_modules`, in the versions that their version ranges resolve to on that day. The banner records the exact versions.
+Without `--entry`, iifeify starts from what a bundler picks for an `import` of the package in browser code: the package's `exports` (conditions `browser`, `import`, `module`, `default`), or else its `browser`, `module` or `main` field.
+
+When that import entry pulls in other packages, iifeify looks at the files the package names for browsers in `browser`, `unpkg` and `jsdelivr`, and takes the first that needs no other package and exports something, or is a classic script. Such a build is the one the package's authors tested, it gives the same output every time, and it is usually what the package's documentation describes for a `<script>` tag: vanilla-jsoneditor gets its `standalone.js`, Chart.js its `chart.umd.min.js` and Vue its `vue.global.js`. When the import entry cannot be bundled at all, those files are tried as well.
+
+Otherwise iifeify bundles the import entry, together with its dependencies from `node_modules` in the versions their ranges resolve to on that day. The banner records the exact versions.
 
 With `--entry` you choose a file inside the package, or a subpath that the package exports:
 
 ```bash
-npx iifeify vanilla-jsoneditor --entry standalone.js
-npx iifeify rxjs --entry operators
+npx -y iifeify vanilla-jsoneditor --entry index.js
+npx -y iifeify rxjs --entry operators
 ```
 
-Some packages ship a ready-made browser file with all dependencies already inside, like `standalone.js` above. Bundling that file gives the same output every time. When a package names such a file in its `browser` field but `exports` points elsewhere, iifeify prints a hint with the `--entry` to use.
+**Classic scripts are used as they are.** A UMD or IIFE build that defines its globals itself, such as `vue.global.js`, is not wrapped in another IIFE, which would hide its global. iifeify writes it with the banner on top, minified unless `--no-minify`. Its global keeps the name the script gives it, so `--global-name` cannot be used with it.
 
 ### The global
 
-- For an ES module package the global is an object with the package's exports. A default export is the property `default`.
-- For a CommonJS package the global is whatever the package assigns to `module.exports`.
-- If the package imports CSS, the styles are written next to the script, with `.css` in place of `.js`.
-- `process.env.NODE_ENV` is replaced by `"production"`.
+Without `--global-name`, the global gets the name the package uses itself:
+
+1. the one its type declarations declare with `export as namespace`, such as `ApexCharts`;
+2. else the one its own UMD or IIFE build assigns, such as `Chart`, `dayjs` or `DOMPurify`;
+3. else a name made from the package name: `chart.js` gives `Chart`, and `vanilla-jsoneditor` gives `VanillaJsonEditor`, spelled as the package's export `JsonEditor`.
+
+What the global holds:
+
+- For an ES module with a default export, the default export, with the module's other exports as its properties. That is what a package's own browser build defines, so `DOMPurify.sanitize()` works as its documentation shows. A default export that cannot have properties, such as a number, leaves the global an object with all exports.
+- For an ES module without a default export, an object with the module's exports.
+- For a CommonJS package, whatever the package assigns to `module.exports`.
+- A classic script defines its globals itself.
+
+If the package imports CSS, the styles are written next to the script, with `.css` in place of `.js`. `process.env.NODE_ENV` is replaced by `"production"`.
 
 ### License information
 
@@ -172,7 +187,9 @@ Plain JavaScript modules, run by Node.js as they are: there is no build step, an
 | `bin/cli.js` | The command line, parsed with [cac](https://github.com/cacjs/cac), and the summary it prints |
 | `src/convert.js` | One conversion from start to end, including the temporary folder |
 | `src/install.js` | Reading the package spec and running `npm install` |
-| `src/bundle.js` | The esbuild call, and the explanation when a package cannot be bundled |
+| `src/entry.js` | Which file to bundle: the import entry, or a browser build, and whether it is a classic script |
+| `src/global.js` | The global's name: from the type declarations, the package's own build, or the package name |
+| `src/bundle.js` | The esbuild calls that probe an entry and build the script, and the explanation when a package cannot be bundled |
 | `src/packages.js` | Which packages ended up in the bundle, and their metadata and license files |
 | `src/banner.js` | The banner and the notices file |
 
@@ -192,7 +209,7 @@ node bin/cli.js ms     # the tool, run from the checkout
 
 ### Tests
 
-Both suites use Node.js's own test runner. `npm test` runs offline: it bundles small packages written into a temporary `node_modules`, and runs the CLI without installing anything. `npm run test:e2e` converts `ms`, `is-odd` and `mkdirp` from the npm registry.
+Both suites use Node.js's own test runner. `npm test` runs offline: it bundles small packages written into a temporary `node_modules`, and runs the CLI on packages in local folders, which npm installs without the registry. `npm run test:e2e` converts `ms`, `is-odd`, `mkdirp`, `vanilla-jsoneditor`, `chart.js` and `dompurify` from the npm registry.
 
 ### CI & Releases
 

package/bin/cli.js

@@ -15,14 +15,14 @@ const cli = cac('iifeify');
 
 cli.command('<package>', 'Turn an npm package into one classic browser script that defines a single global')
     .usage('<package>[@version] [options]')
-    .option('-e, --entry <path>', 'File or subpath inside the package to bundle (default: its own browser entry)')
-    .option('-g, --global-name <name>', 'Global variable the script defines (default: the package name in PascalCase)')
+    .option('-e, --entry <path>', 'File or subpath inside the package to bundle (default: detected)')
+    .option('-g, --global-name <name>', 'Global variable the script defines (default: detected)')
     .option('-o, --outfile <file>', 'Where to write the script (default: ./<package>.iife.js)')
     .option('--minify', 'Minify the output; --no-minify keeps it readable', { default: true })
     .option('--target <list>', 'Language level of the output, e.g. es2020 (default: esnext)')
     .option('--notices', 'Also write the full license texts of all bundled packages, e.g. to ms.iife.LICENSES.txt')
-    .example('  $ iifeify ms')
-    .example('  $ iifeify vanilla-jsoneditor@3.13.0 --entry standalone.js --global-name VanillaJsonEditor')
+    .example('  $ iifeify vanilla-jsoneditor@3.13.0')
+    .example('  $ iifeify chart.js --entry dist/chart.js --global-name ChartModule')
     .action(async (spec, options) => {
         const result = await convert({
             spec: String(spec),
@@ -70,7 +70,7 @@ function endStep(outcome) {
 }
 
 /** @param {Awaited<ReturnType<typeof convert>>} result */
-function report({ files, bytes, packages, entry, globalName, warnings, hint }) {
+function report({ files, bytes, packages, entry, global, warnings }) {
     const [root, ...dependencies] = packages;
     // Relative to the current folder if the file is inside it, else in full.
     const shown = file => {
@@ -82,8 +82,9 @@ function report({ files, bytes, packages, entry, globalName, warnings, hint }) {
 
     console.log(`Wrote ${shown(files.js)} (${size})`);
     console.log(`  package  ${described(root)}`);
-    console.log(`  entry    ${entry}`);
-    console.log(`  global   ${globalName}`);
+    console.log(`  entry    ${entry.file} (${entry.reason})`);
+    const holds = global.defaultExport ? ', holds the default export' : '';
+    console.log(`  global   ${global.name ? `${global.name} (${global.reason}${holds})` : global.reason}`);
     if (dependencies.length > 0) {
         console.log(`  bundled  ${dependencies.length} ${dependencies.length === 1 ? 'dependency' : 'dependencies'}`);
         for (const dependency of dependencies) {
@@ -100,9 +101,6 @@ function report({ files, bytes, packages, entry, globalName, warnings, hint }) {
     for (const warning of warnings) {
         console.error(`\n${warning}`);
     }
-    if (hint) {
-        console.log(`\nHint: ${hint}`);
-    }
 }
 
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "iifeify",
-    "version": "1.1.0",
+    "version": "2.0.0",
     "description": "Turn any browser-compatible npm package into a single classic script (an IIFE that defines one global), with a generated license banner.",
     "license": "MIT",
     "author": "Florian Noever",
@@ -45,7 +45,7 @@
         "lint": "eslint --max-warnings 0",
         "test": "node --test \"test/*.test.js\"",
         "test:e2e": "node --test \"test/e2e/*.test.js\"",
-        "build:example": "node bin/cli.js vanilla-jsoneditor@3.13.0 --entry standalone.js --global-name VanillaJsonEditor --outfile examples/bc-json-viewer/vanilla-jsoneditor.iife.js"
+        "build:example": "node bin/cli.js vanilla-jsoneditor@3.13.0 --outfile examples/bc-json-viewer/vanilla-jsoneditor.iife.js"
     },
     "dependencies": {
         "cac": "^7.1.0",

package/src/bundle.js

@@ -1,6 +1,6 @@
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { isBuiltin } from 'node:module';
-import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { relative, resolve } from 'node:path';
 import * as esbuild from 'esbuild';
 
 import { ConversionError, UsageError } from './errors.js';
@@ -11,6 +11,30 @@ const OUT_JS = 'out.js';
 const MAX_ERRORS_SHOWN = 10;
 const MESSAGE_FORMAT = { color: false, terminalWidth: 100 };
 
+// What the probes and the build have in common, so that both see the package alike.
+const COMMON = /** @type {const} */ ({
+    bundle: true,
+    // Makes an import of a Node built-in such as "fs" an error.
+    platform: 'browser',
+    // esbuild sets this by itself only when minifying.
+    define: { 'process.env.NODE_ENV': '"production"' },
+    outfile: OUT_JS,
+    write: false,
+    metafile: true,
+    logLevel: 'silent',
+});
+
+/**
+ * What bundling an entry point as an ES module tells about it.
+ *
+ * @typedef {object} Probe
+ * @property {string} entryPoint        as handed to esbuild: a file, or a package path
+ * @property {string} file              the entry file, as an absolute path
+ * @property {'esm' | 'cjs' | undefined} format   undefined for a file without import, export or require
+ * @property {string[]} exports         the names the entry exports
+ * @property {string[]} inputs          the files whose code is in the bundle, as absolute paths
+ */
+
 /**
  * Rejects a global name or target that esbuild will not accept. esbuild defines the rules for
  * both, so it is asked directly. This is quick, so it can run before anything is installed.
@@ -30,95 +54,141 @@ export async function checkOptions({ globalName, target }) {
 }
 
 /**
- * Bundles an installed package into one classic script that defines a global.
+ * Bundles an entry point as an ES module, only to learn what it is: which file, what kind of
+ * code, what it exports, and which files it takes in.
  *
  * @param {object} options
- * @param {string} options.workDir       folder whose node_modules holds the package
- * @param {string} options.name          the package's folder name inside node_modules
- * @param {string} options.dir           the package's folder
- * @param {string} options.label         the package in messages, such as "ms 2.1.3"
- * @param {string} [options.entry]       file or subpath inside the package; default is its browser entry
- * @param {string} options.globalName
+ * @param {string} options.workDir      folder whose node_modules holds the package
+ * @param {string} options.entryPoint   a file, or a package path such as "ms" or "rxjs/operators"
+ * @param {string} options.label        the package in messages, such as "ms 2.1.3"
+ * @param {string} [options.entry]      what the user gave as --entry, for messages
+ * @returns {Promise<Probe>}
+ */
+export async function probe({ workDir, entryPoint, label, entry }) {
+    const result = await build({ ...COMMON, absWorkingDir: workDir, entryPoints: [entryPoint], format: 'esm' }, label, entryPoint, entry);
+    const output = result.metafile.outputs[OUT_JS];
+    // A build that succeeds always has an entry point.
+    const entryFile = /** @type {string} */ (output.entryPoint);
+    return {
+        entryPoint,
+        file: resolve(workDir, entryFile),
+        format: result.metafile.inputs[entryFile]?.format,
+        exports: output.exports,
+        inputs: inputsOf(result.metafile, workDir),
+    };
+}
+
+/**
+ * Builds the script. A module is bundled into an IIFE that defines the global; a classic script
+ * defines its globals itself, so it is only minified, or copied as it is.
+ *
+ * @param {object} options
+ * @param {string} options.workDir
+ * @param {import('./entry.js').Plan} options.plan   what to build, from chooseEntry
+ * @param {string} options.label
+ * @param {string} [options.entry]
+ * @param {string} [options.globalName]   the global a module's IIFE defines
  * @param {boolean} options.minify
  * @param {string[]} [options.target]
- * @returns {Promise<{ js: string, css?: string, entry: string, inputs: string[], warnings: string[] }>}
- *     the script, the stylesheet if the package imports CSS, the entry file, the files whose code
- *     is in the output (both as absolute paths), and esbuild's warnings as text
+ * @returns {Promise<{ js: string, css?: string, entry: string, inputs: string[], warnings: string[],
+ *     defaultExport: boolean }>} the script, the stylesheet if the package imports CSS, the entry
+ *     file, the files whose code is in the output (both as absolute paths), esbuild's warnings as
+ *     text, and whether the global holds the module's default export rather than all its exports
  */
-export async function bundle({ workDir, name, dir, label, entry, globalName, minify, target }) {
-    const entryPoint = entryPointFor(name, dir, entry);
-
-    let result;
-    try {
-        result = await esbuild.build({
-            absWorkingDir: workDir,
-            entryPoints: [entryPoint],
-            outfile: OUT_JS,
-            write: false,
-            metafile: true,
-            bundle: true,
-            format: 'iife',
-            globalName,
-            // Makes an import of a Node built-in such as "fs" an error.
-            platform: 'browser',
-            minify,
-            target,
-            legalComments: 'eof',
-            // esbuild sets this by itself only when minifying.
-            define: { 'process.env.NODE_ENV': '"production"' },
-            logLevel: 'silent',
-        });
-    } catch (error) {
-        if (!Array.isArray(error.errors)) {
-            throw error;
-        }
-        throw new ConversionError(await explainFailure(error.errors, label, entryPoint, entry));
+export async function bundle({ workDir, plan, label, entry, globalName, minify, target }) {
+    if (plan.kind === 'script') {
+        return minifyScript({ workDir, file: plan.probe.file, label, minify, target });
     }
 
-    const { outputs } = result.metafile;
-    const inputs = new Set();
-    for (const output of Object.values(outputs)) {
-        for (const [file, { bytesInOutput }] of Object.entries(output.inputs)) {
-            if (bytesInOutput > 0) {
-                inputs.add(resolve(workDir, file));
-            }
-        }
-    }
-    const text = extension => result.outputFiles.find(file => file.path.endsWith(extension))?.text;
+    // Holding the default export is what a library's own browser build does, and what its
+    // documentation then shows: DOMPurify.sanitize() rather than DOMPurify.default.sanitize().
+    const defaultExport = plan.probe.format === 'esm' && plan.probe.exports.includes('default');
+    const { entryPoint } = plan.probe;
+    const result = await build({
+        ...COMMON,
+        absWorkingDir: workDir,
+        entryPoints: [entryPoint],
+        format: 'iife',
+        globalName,
+        minify,
+        target,
+        legalComments: 'eof',
+        footer: defaultExport ? { js: holdDefaultExport(/** @type {string} */ (globalName)) } : undefined,
+    }, label, entryPoint, entry);
 
-    // A build that succeeds always has a script and an entry point.
+    const text = extension => result.outputFiles.find(file => file.path.endsWith(extension))?.text;
     return {
+        // A build that succeeds always has a script and an entry point.
         js: /** @type {string} */ (text('.js')),
         css: text('.css'),
-        entry: resolve(workDir, /** @type {string} */ (outputs[OUT_JS].entryPoint)),
-        // A module that the package's "browser" field switches off is listed under a made-up path.
-        inputs: [...inputs].filter(existsSync),
+        entry: resolve(workDir, /** @type {string} */ (result.metafile.outputs[OUT_JS].entryPoint)),
+        inputs: inputsOf(result.metafile, workDir),
         warnings: await esbuild.formatMessages(result.warnings, { kind: 'warning', ...MESSAGE_FORMAT }),
+        defaultExport,
     };
 }
 
 /**
- * What to hand esbuild as entry point: a file inside the package, or a package path. esbuild
- * resolves a package path like an import in browser code: through "exports" with the conditions
- * browser, import, module and default, else through the fields browser, module and main.
+ * Code after the IIFE that makes the global the module's default export. The module's other
+ * exports become properties of it, unless it has a property of that name already. A default
+ * export that cannot have properties, such as a number, leaves the global as it was.
  */
-function entryPointFor(name, dir, entry) {
-    if (!entry) {
-        return name;
+function holdDefaultExport(globalName) {
+    return `${globalName}=function(n){var d=n.default,k;if(d===null||typeof d!=="object"&&typeof d!=="function")return n;`
+        + `for(k in n)if(k!=="default"&&!(k in d))try{d[k]=n[k]}catch(e){}return d}(${globalName});`;
+}
+
+/**
+ * A classic script, minified without a format: esbuild then keeps the names at its top level,
+ * which are the globals it defines. Without --minify and --target it stays exactly as it is.
+ */
+async function minifyScript({ workDir, file, label, minify, target }) {
+    const source = readFileSync(file, 'utf8');
+    const script = { css: undefined, entry: file, inputs: [file], defaultExport: false };
+    if (!minify && !target) {
+        return { ...script, js: source.endsWith('\n') ? source : `${source}\n`, warnings: [] };
     }
 
-    const file = resolve(dir, entry);
-    const fromPackage = relative(dir, file);
-    if (fromPackage === '..' || fromPackage.startsWith(`..${sep}`) || isAbsolute(fromPackage)) {
-        throw new UsageError(`--entry must name something inside the package, got: ${entry}`);
+    const sourcefile = relative(workDir, file).replaceAll('\\', '/');
+    try {
+        const result = await esbuild.transform(source, { minify, target, legalComments: 'eof', sourcefile, logLevel: 'silent' });
+        return { ...script, js: result.code, warnings: await esbuild.formatMessages(result.warnings, { kind: 'warning', ...MESSAGE_FORMAT }) };
+    } catch (error) {
+        if (!Array.isArray(error.errors)) {
+            throw error;
+        }
+        throw new ConversionError(await explainFailure(error.errors, label, sourcefile));
     }
-    if (!fromPackage) {
-        return name;
+}
+
+/**
+ * Runs esbuild, and explains a failure.
+ *
+ * @param {import('esbuild').BuildOptions & { metafile: true, write: false }} options
+ */
+async function build(options, label, entryPoint, entry) {
+    try {
+        return await esbuild.build(options);
+    } catch (error) {
+        if (!Array.isArray(error.errors)) {
+            throw error;
+        }
+        throw new ConversionError(await explainFailure(error.errors, label, entryPoint, entry));
     }
-    if (statSync(file, { throwIfNoEntry: false })?.isFile()) {
-        return file;
+}
+
+/** The files whose code ends up in the output, as absolute paths. */
+function inputsOf(metafile, workDir) {
+    const inputs = new Set();
+    for (const output of Object.values(metafile.outputs)) {
+        for (const [file, { bytesInOutput }] of Object.entries(output.inputs)) {
+            if (bytesInOutput > 0) {
+                inputs.add(resolve(workDir, file));
+            }
+        }
     }
-    return `${name}/${fromPackage.replaceAll('\\', '/')}`; // a subpath from the package's "exports"
+    // A module that the package's "browser" field switches off is listed under a made-up path.
+    return [...inputs].filter(existsSync);
 }
 
 /** Says in one sentence why the package cannot be bundled, followed by esbuild's own messages. */

package/src/convert.js

@@ -1,9 +1,12 @@
-import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 
 import { renderBanner, renderNotices } from './banner.js';
 import { bundle, checkOptions } from './bundle.js';
+import { chooseEntry } from './entry.js';
+import { UsageError } from './errors.js';
+import { chooseGlobalName, ownGlobal } from './global.js';
 import { installPackage, parseSpec } from './install.js';
 import { bundledPackages } from './packages.js';
 
@@ -18,15 +21,18 @@ import { bundledPackages } from './packages.js';
  *
  * @param {object} options
  * @param {string} options.spec            package to convert, such as "vanilla-jsoneditor@3.13.0"
- * @param {string} [options.entry]         file or subpath inside the package; default is its browser entry
- * @param {string} [options.globalName]    default is the package name in PascalCase
+ * @param {string} [options.entry]         file or subpath inside the package; detected if not given
+ * @param {string} [options.globalName]    detected if not given
  * @param {string} [options.outfile]       default is <package name>.iife.js in the current folder
  * @param {boolean} [options.minify]
  * @param {string[]} [options.target]      esbuild targets such as ["es2020"]
  * @param {boolean} [options.notices]      also write the full license texts next to the script
  * @param {(step: Step) => void} [options.onStep]  called as each step starts, to report progress
  * @returns {Promise<{ files: { js: string, css?: string, notices?: string }, bytes: number,
- *     packages: object[], entry: string, globalName: string, warnings: string[], hint?: string }>}
+ *     packages: object[], entry: { file: string, reason: string },
+ *     global: { name?: string, reason: string, defaultExport: boolean }, warnings: string[] }>}
+ *     the entry and the global come with the reason they were chosen; a classic script's global
+ *     has no name when it cannot be read from the script
  */
 export async function convert({ spec, entry, globalName: requestedGlobalName, outfile, minify = true, target, notices = false, onStep }) {
     const wanted = parseSpec(spec);
@@ -38,11 +44,14 @@ export async function convert({ spec, entry, globalName: requestedGlobalName, ou
     try {
         onStep?.({ name: 'install', spec });
         const { dir, manifest } = await installPackage(wanted, workDir);
-        const globalName = requestedGlobalName ?? defaultGlobalName(manifest.name);
 
         const label = `${manifest.name} ${manifest.version}`;
         onStep?.({ name: 'bundle', label });
-        const built = await bundle({ workDir, name: wanted.name, dir, label, entry, globalName, minify, target });
+        const plan = await chooseEntry({ workDir, name: wanted.name, dir, manifest, label, entry });
+        const entryFile = relative(dir, plan.probe.file).replaceAll('\\', '/');
+        const global = await globalFor({ plan, entryFile, requestedGlobalName, packageName: manifest.name, dir, manifest });
+
+        const built = await bundle({ workDir, plan, label, entry, globalName: global.name, minify, target });
         const packages = bundledPackages(built.inputs, dir);
         const banner = renderBanner(packages);
 
@@ -65,10 +74,9 @@ export async function convert({ spec, entry, globalName: requestedGlobalName, ou
             files,
             bytes: Buffer.byteLength(script),
             packages,
-            entry: relative(dir, built.entry).replaceAll('\\', '/'),
-            globalName,
+            entry: { file: entryFile, reason: plan.kind === 'script' ? `${plan.reason}, a classic script already` : plan.reason },
+            global: { ...global, defaultExport: built.defaultExport },
             warnings: [...built.warnings.map(warning => warning.trim()), ...unlicensed],
-            hint: entry ? undefined : prebuiltHint(manifest, dir, built.entry),
         };
     } finally {
         try {
@@ -80,35 +88,30 @@ export async function convert({ spec, entry, globalName: requestedGlobalName, ou
     }
 }
 
-/** "vanilla-jsoneditor" and "@scope/vanilla-jsoneditor" both give "VanillaJsoneditor". */
-export function defaultGlobalName(packageName) {
-    const words = unscoped(packageName).split(/[^A-Za-z0-9]+/).filter(Boolean);
-    const name = words.map(word => word[0].toUpperCase() + word.slice(1)).join('');
-    return /^[A-Za-z]/.test(name) ? name : `_${name}`;
-}
-
 /** "@scope/vanilla-jsoneditor" gives "vanilla-jsoneditor.iife.js". */
 export function defaultOutfile(packageName) {
-    return `${unscoped(packageName)}.iife.js`;
-}
-
-function unscoped(packageName) {
-    return packageName.slice(packageName.indexOf('/') + 1);
+    return `${packageName.slice(packageName.indexOf('/') + 1)}.iife.js`;
 }
 
 /**
- * Some packages point "exports" at a file that needs its dependencies bundled in, and "browser" at
- * a ready-made file that contains them. Bundlers follow "exports", so the ready-made file takes --entry.
+ * The global's name, and where it comes from. A classic script defines its globals itself, so
+ * there is nothing to name; the summary shows the one it defines, if that can be read from it.
+ *
+ * @returns {Promise<{ name?: string, reason: string }>}
  */
-function prebuiltHint(manifest, dir, entryFile) {
-    if (typeof manifest.browser !== 'string') {
-        return undefined;
+async function globalFor({ plan, entryFile, requestedGlobalName, packageName, dir, manifest }) {
+    if (plan.kind === 'script') {
+        const own = ownGlobal(plan.probe.file);
+        if (requestedGlobalName) {
+            throw new UsageError(
+                `${entryFile} is a classic script that defines its own global${own ? `, ${own}` : ''}, so --global-name cannot rename it. `
+                + 'Leave out --global-name, or choose another file with --entry.'
+            );
+        }
+        return { name: own, reason: 'set by the script itself' };
     }
-
-    const prebuilt = resolve(dir, manifest.browser);
-    if (prebuilt === entryFile || !existsSync(prebuilt)) {
-        return undefined;
+    if (requestedGlobalName) {
+        return { name: requestedGlobalName, reason: 'given with --global-name' };
     }
-    const entry = relative(dir, prebuilt).replaceAll('\\', '/');
-    return `${manifest.name} also ships a prebuilt browser file. To bundle that instead, add: --entry ${entry}`;
+    return chooseGlobalName({ packageName, dir, manifest, plan });
 }

package/src/entry.js

@@ -0,0 +1,128 @@
+import { statSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { probe } from './bundle.js';
+import { UsageError } from './errors.js';
+import { ownGlobal } from './global.js';
+import { packageDirOf } from './packages.js';
+
+/**
+ * What to build, and why.
+ *
+ * @typedef {object} Plan
+ * @property {import('./bundle.js').Probe} probe
+ * @property {'module' | 'script'} kind   a module is bundled into an IIFE. A classic script defines
+ *     its globals itself; wrapping it would hide them inside the IIFE, so it is used as it is.
+ * @property {string} reason              why this entry, for the summary
+ */
+
+/**
+ * Chooses the entry point: the one the user named, else the package's import entry. When that
+ * needs other packages and the package names a browser build that does not, the browser build:
+ * it is the file the package's authors tested, and the one its documentation describes.
+ *
+ * @param {object} options
+ * @param {string} options.workDir
+ * @param {string} options.name       the package's folder name inside node_modules
+ * @param {string} options.dir        the package's folder
+ * @param {object} options.manifest   its package.json
+ * @param {string} options.label      the package in messages, such as "ms 2.1.3"
+ * @param {string} [options.entry]    file or subpath inside the package, given with --entry
+ * @returns {Promise<Plan>}
+ */
+export async function chooseEntry({ workDir, name, dir, manifest, label, entry }) {
+    if (entry) {
+        return plan(await probe({ workDir, entryPoint: entryPointFor(name, dir, entry), label, entry }), 'given with --entry');
+    }
+
+    // esbuild resolves the package name like an import in browser code: through "exports" with
+    // the conditions browser, import, module and default, else through browser, module and main.
+    let imported;
+    let failure;
+    try {
+        imported = await probe({ workDir, entryPoint: name, label });
+    } catch (error) {
+        failure = error;
+    }
+    if (imported && usesOnlyItself(imported, dir)) {
+        return plan(imported, 'the import entry');
+    }
+
+    for (const file of browserBuilds(dir, manifest)) {
+        if (file === imported?.file) {
+            continue;
+        }
+        let build;
+        try {
+            build = await probe({ workDir, entryPoint: file, label });
+        } catch {
+            continue; // a browser build that cannot be bundled either is no better choice
+        }
+        const candidate = plan(build, 'browser build without dependencies');
+        // A module needs exports, or its global would be empty; a script defines its own.
+        if (usesOnlyItself(build, dir) && (candidate.kind === 'script' || build.exports.length > 0)) {
+            return candidate;
+        }
+    }
+
+    if (imported) {
+        return plan(imported, 'the import entry');
+    }
+    throw failure;
+}
+
+/**
+ * The files a package names for use in a browser: "browser", and "unpkg" and "jsdelivr", the
+ * files those CDNs serve for a plain <script> tag.
+ */
+export function browserBuilds(dir, manifest) {
+    const files = [manifest.browser, manifest.unpkg, manifest.jsdelivr]
+        .filter(field => typeof field === 'string')
+        .map(field => resolve(dir, field))
+        .filter(file => isInside(dir, file) && statSync(file, { throwIfNoEntry: false })?.isFile());
+    return [...new Set(files)];
+}
+
+function plan(found, reason) {
+    return { probe: found, kind: isClassicScript(found) ? /** @type {const} */ ('script') : /** @type {const} */ ('module'), reason };
+}
+
+/**
+ * A file that defines its globals itself, as a UMD or IIFE build does: one without import, export
+ * or require, or one that is an ES module only because of its package's "type", imports and
+ * exports nothing, and assigns a global.
+ *
+ * @param {import('./bundle.js').Probe} found
+ */
+function isClassicScript({ file, format, exports, inputs }) {
+    if (!/\.c?js$/i.test(file) || inputs.length > 1) {
+        return false;
+    }
+    return format === undefined || (format === 'esm' && exports.length === 0 && ownGlobal(file) !== undefined);
+}
+
+/** Whether every file in the bundle belongs to the package itself. */
+function usesOnlyItself({ inputs }, dir) {
+    return inputs.every(file => resolve(packageDirOf(file) ?? file) === resolve(dir));
+}
+
+function isInside(dir, file) {
+    const fromDir = relative(dir, file);
+    return fromDir !== '' && fromDir !== '..' && !fromDir.startsWith(`..${sep}`) && !isAbsolute(fromDir);
+}
+
+/** What to hand esbuild for --entry: a file inside the package, or a subpath of its "exports". */
+function entryPointFor(name, dir, entry) {
+    const file = resolve(dir, entry);
+    const fromPackage = relative(dir, file);
+    if (fromPackage === '..' || fromPackage.startsWith(`..${sep}`) || isAbsolute(fromPackage)) {
+        throw new UsageError(`--entry must name something inside the package, got: ${entry}`);
+    }
+    if (!fromPackage) {
+        return name;
+    }
+    if (statSync(file, { throwIfNoEntry: false })?.isFile()) {
+        return file;
+    }
+    return `${name}/${fromPackage.replaceAll('\\', '/')}`; // a subpath from the package's "exports"
+}

package/src/global.js

@@ -0,0 +1,165 @@
+import { readFileSync, statSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { checkOptions } from './bundle.js';
+
+const ID = '[A-Za-z_$][\\w$]*';
+
+// How UMD builds assign their global, as rollup, webpack and browserify write it, minified or not:
+// root["Name"] = factory(), global.Name = factory(), (t = ... || self).Name = e(),
+// global.Name = global.Name || {} and (e = e || self).Name = {}.
+const UMD_ASSIGNMENTS = [
+    new RegExp(`\\[\\s*["'](${ID})["']\\s*\\]\\s*=\\s*${ID}\\s*\\(`, 'g'),
+    new RegExp(`\\.\\s*(${ID})\\s*=\\s*${ID}\\s*\\(`, 'g'),
+    new RegExp(`\\.\\s*(${ID})\\s*=\\s*(?:${ID}\\.\\1\\s*\\|\\|\\s*)?\\{\\s*\\}`, 'g'),
+];
+// A UMD header ends where the factory is handed over: }(this, function ...) and the like.
+const UMD_HEADER_END = /\}\s*\)?\s*\(\s*(?:this|self|window|globalThis|"undefined"|typeof)/;
+// An IIFE build starts with its global: var Name = (function (exports) {, var Name = (() => {,
+// var Name=function(e){. The same line further down is only a variable of some module.
+const IIFE = new RegExp(`^var\\s+(${ID})\\s*=\\s*(?:\\(\\s*)?(?:function\\b|\\(\\s*\\)\\s*=>|async\\b)`);
+const LEADING_COMMENTS = /^(?:\s*(?:\/\*[\s\S]*?\*\/|\/\/[^\n]*\n))*\s*(?:["']use strict["'];?\s*)?/;
+
+// Names a UMD header assigns that are not the library's global.
+const NOT_A_GLOBAL = new Set(['exports', 'module', 'amd', 'define', 'require', 'window', 'self', 'globalThis', 'global', 'document']);
+
+/**
+ * Chooses the global's name when --global-name is not given, from what the package says itself:
+ * the global its type declarations declare, the one its own browser build assigns, or else a
+ * name made from the package name.
+ *
+ * @param {object} options
+ * @param {string} options.packageName
+ * @param {string} options.dir        the package's folder
+ * @param {object} options.manifest   its package.json
+ * @param {import('./entry.js').Plan} options.plan
+ * @returns {Promise<{ name: string, reason: string }>}
+ */
+export async function chooseGlobalName({ packageName, dir, manifest, plan }) {
+    const candidates = [];
+    const declared = typesNamespace(dir, manifest);
+    if (declared) {
+        candidates.push({ name: declared, reason: 'from the type declarations' });
+    }
+    for (const file of [plan.probe.file, ...packageFiles(dir, manifest)]) {
+        const name = ownGlobal(file);
+        if (name) {
+            candidates.push({ name, reason: `from ${relative(dir, file).replaceAll('\\', '/')}` });
+        }
+    }
+
+    for (const candidate of candidates) {
+        if (await isUsable(candidate.name)) {
+            return candidate;
+        }
+    }
+    return { name: guessGlobalName(packageName, plan.probe.exports), reason: 'from the package name' };
+}
+
+/**
+ * The global a UMD or IIFE build assigns, read from its first lines, such as "Chart" from
+ * Chart.js's chart.umd.min.js. Undefined for any other file.
+ */
+export function ownGlobal(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8').slice(0, 20000).replace(LEADING_COMMENTS, '');
+    } catch {
+        return undefined;
+    }
+
+    // A UMD header always checks for an AMD loader; a compiled CommonJS module does not.
+    const start = text.slice(0, 2500);
+    if (/define\.amd/.test(start)) {
+        const end = start.search(UMD_HEADER_END);
+        const header = end === -1 ? start : start.slice(0, end);
+        // The header assigns module.exports first and the global last.
+        const assigned = UMD_ASSIGNMENTS.flatMap(pattern => [...header.matchAll(pattern)])
+            .sort((a, b) => /** @type {number} */ (a.index) - /** @type {number} */ (b.index))
+            .map(match => match[1])
+            .filter(name => !NOT_A_GLOBAL.has(name));
+        if (assigned.length > 0) {
+            return assigned.at(-1);
+        }
+    }
+    const iife = IIFE.exec(text.slice(0, 3000))?.[1];
+    return iife && !NOT_A_GLOBAL.has(iife) ? iife : undefined;
+}
+
+/** The global a package's type declarations declare with "export as namespace Name;". */
+export function typesNamespace(dir, manifest) {
+    for (const field of [manifest.types, manifest.typings, 'index.d.ts']) {
+        const file = typeof field === 'string' ? resolve(dir, field) : undefined;
+        if (file && isInside(dir, file) && statSync(file, { throwIfNoEntry: false })?.isFile()) {
+            return /^\s*export\s+as\s+namespace\s+([A-Za-z_$][\w$]*)\s*;/m.exec(readFileSync(file, 'utf8'))?.[1];
+        }
+    }
+    return undefined;
+}
+
+/**
+ * A global name made from the package name, for a package that names none itself:
+ * "vanilla-jsoneditor" gives "VanillaJsonEditor" when the package exports JsonEditor, "chart.js"
+ * gives "Chart", and "@scope/my-lib" gives "ScopeMyLib".
+ *
+ * @param {string} packageName
+ * @param {string[]} [exportNames]   the names the package exports, whose spelling is taken over
+ */
+export function guessGlobalName(packageName, exportNames = []) {
+    const [scope, bare] = packageName.startsWith('@') ? packageName.slice(1).split('/') : [undefined, packageName];
+    // "chart.js" and "highlight.js" are named after their language, "htmx.org" after its site.
+    const words = [scope, bare.replace(/[.-]js$/i, '').replace(/\.(?:org|io|com|net|dev)$/i, '')]
+        .filter(part => part !== undefined)
+        .flatMap(part => part.split(/[^A-Za-z0-9]+/))
+        .filter(Boolean);
+
+    // A word that an export spells out, such as "jsoneditor" for JsonEditor or "sortablejs" for
+    // Sortable, takes that spelling.
+    const spellings = new Map();
+    for (const name of exportNames) {
+        for (const key of [name.toLowerCase(), `${name.toLowerCase()}js`]) {
+            spellings.set(key, [...(spellings.get(key) ?? []), name]);
+        }
+    }
+    const name = words.map(word => spell(word, spellings.get(word.toLowerCase()))).join('');
+    return /^[A-Za-z]/.test(name) ? name : `_${name}`;
+}
+
+/**
+ * Of several spellings, JsonEditor rather than JSONEditor: the one with the fewest capitals,
+ * but at least one. Without any spelling, the word with a capital first letter.
+ */
+function spell(word, spellings) {
+    if (!spellings) {
+        return word[0].toUpperCase() + word.slice(1);
+    }
+    const capitals = name => name.replace(/[^A-Z]/g, '').length;
+    const cased = spellings.filter(name => capitals(name) > 0).sort((a, b) => capitals(a) - capitals(b));
+    return cased[0] ?? spellings[0];
+}
+
+/** The files a package's own browser build can be in. */
+function packageFiles(dir, manifest) {
+    const files = [manifest.unpkg, manifest.jsdelivr, manifest.browser, manifest.main]
+        .filter(field => typeof field === 'string')
+        .map(field => resolve(dir, field))
+        .filter(file => isInside(dir, file) && statSync(file, { throwIfNoEntry: false })?.isFile());
+    return [...new Set(files)];
+}
+
+async function isUsable(name) {
+    if (NOT_A_GLOBAL.has(name)) {
+        return false;
+    }
+    try {
+        await checkOptions({ globalName: name });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function isInside(dir, file) {
+    const fromDir = relative(dir, file);
+    return fromDir !== '' && fromDir !== '..' && !fromDir.startsWith(`..${sep}`) && !isAbsolute(fromDir);
+}