@bobfrankston/importgen 0.1.13 → 0.1.15

package/.claude/settings.local.json

@@ -3,7 +3,8 @@
     "allow": [
       "Bash(npm run build:*)",
       "Bash(npmglobalize)",
-      "Bash(npx tsc)"
+      "Bash(npx tsc)",
+      "Bash(node index.js:*)"
     ]
   }
 }

package/README.md

@@ -1,8 +1,20 @@
 # @bobfrankston/importgen
 
-Generate ES Module import maps from package.json dependencies for native browser module loading.
+Use the same npm packages and `import` statements in the browser as in Node.js/Bun -- no bundler required.
 
-## Installation
+## Why
+
+In Node.js you write:
+
+```typescript
+import { formatDate } from "date-utils";
+```
+
+Node resolves `date-utils` by looking in `node_modules`. Browsers can't do that. Normally you'd need a bundler (webpack, rollup, etc.) to make bare module specifiers work.
+
+Browsers now support [import maps](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) -- a `<script type="importmap">` block that maps package names to file paths. `importgen` reads your `package.json` and generates this import map automatically, injecting it into your HTML file. Your code stays identical between Node and browser -- transparent, no changes needed.
+
+## Install
 
 ```bash
 npm install -g @bobfrankston/importgen
@@ -10,82 +22,172 @@ npm install -g @bobfrankston/importgen
 
 ## Usage
 
-In a directory with `package.json` and `index.html`:
+Run from your project directory (containing `package.json` and your HTML file):
 
 ```bash
-# Generate once
+importgen [htmlfile] [--watch|-w]
+```
+
+```bash
+# Generate import map in index.html (default)
 importgen
 
-# Watch for package.json changes
-importgen -w
+# Specify a different HTML file
+importgen default.htm
+importgen app.html
+
+# Watch mode: regenerate whenever package.json changes
+importgen --watch
+importgen default.htm --watch
 ```
 
-## Automatic Generation with VS Code Tasks
+`importgen` reads dependencies from `package.json` in the current directory and injects the import map into the HTML file.
+
+If no HTML file is specified, it searches for `index.html`, `default.html`, `default.htm` (in that order) and uses the first one found.
+
+If the HTML already has a `<script type="importmap">` block, it is replaced in place. Otherwise the block is inserted before `</head>`.
 
-Add to `.vscode/tasks.json`:
+## What It Generates
+
+Given a `package.json` like:
 
 ```json
 {
-  "version": "2.0.0",
-  "tasks": [
-    {
-      "label": "importgen: watch",
-      "type": "shell",
-      "command": "importgen",
-      "args": ["-w"],
-      "runOptions": {
-        "runOn": "folderOpen"
-      },
-      "isBackground": true
+  "dependencies": {
+    "date-utils": "^2.0.0",
+    "my-ui-lib": "file:../shared/my-ui-lib"
+  }
+}
+```
+
+`importgen` produces:
+
+```html
+<script type="importmap">
+{
+    "imports": {
+        "date-utils": "./node_modules/date-utils/index.js",
+        "my-ui-lib": "./node_modules/my-ui-lib/index.js",
+        "color-convert": "./node_modules/color-convert/index.js"
     }
-  ]
 }
+</script>
+```
+
+Transitive dependencies are included automatically -- if `my-ui-lib` depends on `color-convert`, it appears in the map too. Circular dependencies are detected and handled.
+
+## Using Imports in the Browser
+
+Once the import map is in your HTML, `<script type="module">` code uses the same imports as Node:
+
+```typescript
+// This works identically in Node AND the browser
+import { formatDate } from "date-utils";
+import { render } from "my-ui-lib";
+import { initApp } from "./app.js";
 ```
 
-## How It Works
+The browser sees `date-utils`, looks it up in the import map, and loads `./node_modules/date-utils/index.js`. Local relative imports (`./app.js`) work as always without the import map.
 
-1. Reads `package.json` dependencies
-2. **Recursively resolves** all transitive dependencies
-3. Handles `file:` protocol dependencies and npm packages
-4. Detects and avoids circular dependencies
-5. Resolves correct entry points using `exports`, `module`, or `main` fields
-6. Generates import map with relative paths from HTML location
-7. Injects or updates `<script type="importmap">` in `index.html`
-8. In watch mode, regenerates when `package.json` changes
+The key point: your TypeScript source files are the same whether they run in Node or the browser. `importgen` just provides the mapping the browser needs to find the packages.
 
-### Circular Dependency Protection
+## How Entry Points Are Resolved
 
-The tool tracks visited packages to prevent infinite loops when packages have circular dependencies (A → B → A). Each package is processed only once.
+For each dependency, `importgen` reads that package's `package.json` and picks the entry point in this order:
 
-## PWA Compatible
+1. `exports["."].import` or `exports["."].default` (modern ESM)
+2. `module` field (ESM convention)
+3. `main` field
+4. `./index.js` (fallback)
+
+## Dependency Types
 
-Generated import maps are static and can be cached by service workers, making this ideal for Progressive Web Apps.
+- **npm versions** (`^1.2.3`) -- resolved from `node_modules/`
+- **`file:` paths** (`file:../path/to/package`) -- resolved relative to `package.json`
+- **`workspace:` references** -- resolved from `node_modules/`
 
-## Example
+## `.dependencies` Override
+
+Add a `.dependencies` field to `package.json` to override resolution paths for specific packages without changing the real `dependencies`:
 
-**package.json:**
 ```json
 {
   "dependencies": {
-    "@bobfrankston/lxlan": "^0.1.0",
-    "@bobfrankston/colorlib": "file:../colorlib"
+    "my-utils": "^1.0.0"
+  },
+  ".dependencies": {
+    "my-utils": "file:../local-my-utils"
   }
 }
 ```
 
-If `lxlan` depends on `lxlan-browser`, and `lxlan-browser` depends on `colorlib`, **all three packages** will be included in the generated import map:
+The import map will use the `.dependencies` path instead of the `node_modules` path for that package.
 
-**Generated in index.html:**
-```html
-<script type="importmap">
-    {
-        "imports": {
-            "@bobfrankston/lxlan": "./node_modules/@bobfrankston/lxlan/index.js",
-            "@bobfrankston/lxlan-browser": "./node_modules/@bobfrankston/lxlan-browser/index.js",
-            "@bobfrankston/colorlib": "../colorlib/index.js"
+## VS Code tasks.json Integration
+
+Add `importgen --watch` as a background task that starts automatically when you open the project. Combined with `tsc --watch`, your import map stays current as you develop.
+
+Example `.vscode/tasks.json`:
+
+```json
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "tsc: watch",
+            "type": "shell",
+            "command": "tsc",
+            "args": ["--watch"],
+            "runOptions": {
+                "runOn": "folderOpen"
+            },
+            "problemMatcher": "$tsc-watch",
+            "isBackground": true,
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "importgen: watch",
+            "type": "shell",
+            "command": "importgen",
+            "args": ["--watch"],
+            "runOptions": {
+                "runOn": "folderOpen"
+            },
+            "isBackground": true,
+            "problemMatcher": {
+                "pattern": {
+                    "regexp": "^$",
+                    "file": 1,
+                    "location": 2,
+                    "message": 3
+                },
+                "background": {
+                    "activeOnStart": true,
+                    "beginsPattern": "^\\[generate-importmap\\].*watching.*$",
+                    "endsPattern": "^\\[generate-importmap\\].*Updated.*$"
+                }
+            }
         }
-    }
-</script>
+    ]
+}
 ```
 
-Note: The tool automatically resolves transitive dependencies and handles both npm packages and `file:` protocol dependencies.
+Key points:
+
+- **`"runOn": "folderOpen"`** starts both tasks automatically when you open the workspace
+- **`"isBackground": true`** keeps them running as persistent watchers
+- The custom `problemMatcher` for importgen tells VS Code this is a long-running watcher, not a one-shot build
+- If your HTML file isn't `index.html`, add it to the args: `"args": ["default.htm", "--watch"]`
+
+Workflow: edit `package.json` (add/remove a dependency) -> `importgen` regenerates the import map in the HTML -> `tsc` recompiles TypeScript -> browser picks up changes on reload.
+
+## PWA Compatible
+
+Generated import maps are static and can be cached by service workers.
+
+## License
+
+MIT

package/index.js

@@ -175,39 +175,24 @@ function generateImportMap(packageJsonPath, htmlFilePath) {
 // Parse CLI arguments
 const args = process.argv.slice(2);
 const watchMode = args.includes('-w') || args.includes('--watch');
+const htmlArg = args.find(a => a !== '-w' && a !== '--watch');
 const packageJsonPath = path.join(process.cwd(), 'package.json');
-// Find HTML file - check command line arg first, then try common names
-function findHtmlFile() {
-    // Check for explicit filename argument (non-flag argument)
-    const htmlArg = args.find(arg => !arg.startsWith('-') && (arg.endsWith('.html') || arg.endsWith('.htm')));
-    if (htmlArg) {
-        const explicitPath = path.join(process.cwd(), htmlArg);
-        if (fs.existsSync(explicitPath)) {
-            return explicitPath;
-        }
-        console.error(`[generate-importmap] Error: ${htmlArg} not found in current directory`);
-        process.exit(1);
-    }
-    // Try common HTML file names in order of preference
-    const candidates = ['index.html', 'default.html', 'default.htm'];
-    for (const candidate of candidates) {
-        const candidatePath = path.join(process.cwd(), candidate);
-        if (fs.existsSync(candidatePath)) {
-            return candidatePath;
-        }
-    }
-    return null;
-}
-const htmlFilePath = findHtmlFile();
+// Resolve HTML file: explicit argument, or search for common names
+const possibleHtmlFiles = ['index.html', 'default.html', 'default.htm'];
+const htmlFileName = htmlArg || possibleHtmlFiles.find(f => fs.existsSync(path.join(process.cwd(), f)));
+const htmlFilePath = htmlFileName ? path.join(process.cwd(), htmlFileName) : null;
 // Check if files exist
 if (!fs.existsSync(packageJsonPath)) {
     console.error('[generate-importmap] Error: package.json not found in current directory');
     process.exit(1);
 }
-if (!htmlFilePath) {
-    console.error('[generate-importmap] Error: index.html not found in current directory');
-    console.error('  Also checked: default.html, default.htm');
-    console.error('  Use: importgen [filename.html] to specify a custom HTML file');
+if (!htmlFilePath || !fs.existsSync(htmlFilePath)) {
+    if (htmlArg) {
+        console.error(`[generate-importmap] Error: ${htmlArg} not found in current directory`);
+    }
+    else {
+        console.error(`[generate-importmap] Error: No HTML file found. Looking for: ${possibleHtmlFiles.join(', ')}`);
+    }
     process.exit(1);
 }
 if (watchMode) {

package/package.json

@@ -1,37 +1,40 @@
-{
-  "name": "@bobfrankston/importgen",
-  "version": "0.1.13",
-  "description": "Generate ES Module import maps from package.json dependencies for native browser module loading",
-  "main": "index.js",
-  "bin": {
-    "importgen": "index.js"
-  },
-  "type": "module",
-  "scripts": {
-    "build": "tsc",
-    "watch": "tsc -w",
-    "preversion": "npm run build",
-    "postversion": "echo Version updated to $(node -p \"require('./package.json').version\")",
-    "release": "git add -A && git diff-index --quiet HEAD || git commit -m 'Build for release' && npm version patch",
-    "installer": "npm run release && npm install -g ."
-  },
-  "keywords": [
-    "import-map",
-    "esm",
-    "browser",
-    "modules",
-    "dependencies"
-  ],
-  "author": "Bob Frankston",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/BobFrankston/importgen.git"
-  },
-  "dependencies": {
-    "chokidar": "^4.0.3"
-  },
-  "devDependencies": {
-    "@types/node": "^25.0.9"
-  }
-}
+{
+  "name": "@bobfrankston/importgen",
+  "version": "0.1.15",
+  "description": "Generate ES Module import maps from package.json dependencies for native browser module loading",
+  "main": "index.js",
+  "bin": {
+    "importgen": "index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "preversion": "npm run build",
+    "postversion": "echo Version updated to $(node -p \"require('./package.json').version\")",
+    "release": "git add -A && git diff-index --quiet HEAD || git commit -m 'Build for release' && npm version patch",
+    "installer": "npm run release && npm install -g ."
+  },
+  "keywords": [
+    "import-map",
+    "esm",
+    "browser",
+    "modules",
+    "dependencies"
+  ],
+  "author": "Bob Frankston",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BobFrankston/importgen.git"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}