@normed/bundle 4.6.3 → 4.7.1

package/CHANGELOG.md

@@ -6,6 +6,10 @@ Given a version number MAJOR.MINOR.PATCH, increment the:
 2. MINOR version when you add functionality in a backwards compatible manner, and
 3. PATCH version when you make backwards compatible bug fixes.
 
+# 4.7.1
+
+* PATCH: Fix `node.attrs is not iterable` error in pug templates when non-Tag AST nodes (e.g. code blocks, mixins, comments) are encountered during asset path rebasing.
+
 # 4.6.3
 
 * PATCH: Fix JavaScript and TypeScript files referenced from `.static.pug` templates being copied verbatim instead of being bundled. Script files (`.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`) are now properly processed through esbuild, bundling imports and transpiling TypeScript, producing `.js` output with correct paths in the generated HTML.

package/README.md

@@ -192,6 +192,53 @@ Common asset types are automatically configured to use esbuild's `file` loader:
 
 This means these files referenced from your CSS/JS will be copied to the output directory and their paths will be rewritten appropriately.
 
+### asset paths
+
+By default, asset paths in the output are relative to the HTML/CSS file that references them. To serve static assets (images, fonts, media files) from a CDN or a specific URL prefix, use the `publicPath` esbuild option:
+
+```json
+{
+  "bundle": {
+    "baseConfig": {
+      "javascript": {
+        "esbuild": {
+          "publicPath": "https://cdn.example.com/assets"
+        }
+      }
+    }
+  }
+}
+```
+
+With this configuration, static asset references like `<img src="logo.png">` in pug/HTML and `url(images/bg.png)` in CSS will be rewritten to use the public path prefix (e.g., `https://cdn.example.com/assets/logo-A1B2C3D4.png`).
+
+**Note:** `publicPath` only affects static assets (images, fonts, media). Links between HTML pages, CSS stylesheets, and JavaScript files discovered in pug templates always use relative paths.
+
+You can also customize how asset filenames are generated using the `assetNames` option:
+
+```json
+{
+  "bundle": {
+    "baseConfig": {
+      "javascript": {
+        "esbuild": {
+          "publicPath": "/static",
+          "assetNames": "assets/[name]-[hash]"
+        }
+      }
+    }
+  }
+}
+```
+
+The `assetNames` template supports the following placeholders:
+- `[name]` - The original filename without extension
+- `[hash]` - A content-based hash for cache busting
+- `[ext]` - The file extension
+- `[dir]` - The directory path relative to the source directory
+
+The default is `[name]-[hash]` for static assets in pug templates. For CSS/JS files discovered in pug templates, the default is `[dir]/[name]-[hash]` to preserve directory structure.
+
 ### external CSS URLs
 
 For CSS files that reference runtime paths (like `/fonts/*` or `/images/*`) that should not be resolved at build time, use the `css.externalUrls` configuration:
@@ -240,6 +287,60 @@ Features:
 
 This works for all HTML attributes that can contain paths (href, src, data, poster, etc.).
 
+### Node-resolved references (`build:` / `copy:`)
+
+Pug templates support two prefixes for referencing files via Node's module resolution (`require.resolve`):
+
+| Prefix | Action |
+|--------|--------|
+| `build:` | Resolve via Node, then compile through the appropriate pipeline (Less→CSS, Pug→HTML, TS→JS) |
+| `copy:` | Resolve via Node, then copy to output with content-hashing |
+
+```pug
+//- Compile a Less file from a shared location
+link(rel="stylesheet" href="build:#shared/styles.less")
+
+//- Copy a vendor CSS file (url() references are rewritten)
+link(rel="stylesheet" href="copy:normalize.css/normalize.css")
+
+//- Copy a vendor JS file as-is
+script(src="copy:bootstrap/dist/js/bootstrap.min.js")
+```
+
+Both prefixes support:
+- **Bare specifiers**: `bootstrap/dist/css/bootstrap.css` — resolves from `node_modules`
+- **`#` subpath imports**: `#shared/styles.less` — resolves via the `imports` field in `package.json`
+
+#### Configuring `#` subpath imports
+
+Add an `imports` field to your `package.json`:
+
+```json
+{
+  "imports": {
+    "#shared/*": "./src/shared/*",
+    "#assets/*": "./src/assets/*"
+  }
+}
+```
+
+This is a standard Node.js feature (v12.19+) that also works natively in esbuild and TypeScript (4.5+). One config, consistent everywhere.
+
+#### `build:` supported file types
+
+| Extension | Pipeline |
+|-----------|----------|
+| `.less` | Less → CSS (via esbuild CSS pipeline) |
+| `.pug` | Pug → HTML |
+| `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` | TypeScript/JavaScript bundling |
+| `.css` | CSS (via esbuild CSS pipeline, handles `url()` rewriting) |
+
+Using `build:` on an unsupported extension emits a warning suggesting `copy:` instead.
+
+#### Deprecation of `pkg:`
+
+The `pkg:` prefix is deprecated in favour of `copy:`. Both work identically — `pkg:` emits a deprecation warning during build. Replace `pkg:normalize.css/normalize.css` with `copy:normalize.css/normalize.css`.
+
 ### analyse
 
 To get a report on bundle content and size enable analysis:
@@ -364,6 +465,16 @@ Now `*.worker.ts` files will be discovered and built with server platform settin
 
 Use `LOG_LEVEL=verbose yarn bundle` to see which patterns are being searched.
 
+# Known issues
+
+### Declaration generation may resolve wrong dependency versions
+
+When `declarations: true` is set, the bundler uses TypeScript's compiler API (`ts.createProgram`) to generate `.d.ts` files. In Yarn PnP environments, this can resolve `@types` packages to the wrong version — e.g. picking up a transitive `@types/node@20` instead of your workspace's direct `@types/node@25`.
+
+This happens because `ts.createCompilerHost` uses filesystem-walking resolution, which goes through PnP's `fs` patch (layer 2) rather than PnP's scope-aware `require` resolution (layer 1). The `fs` patch makes all zip cache contents readable but doesn't enforce dependency scoping, so transitive dependencies can leak into type resolution. The Yarn TypeScript SDK solves this for `tsc` and `tsserver` by wrapping them to call `.pnp.cjs.setup()`, but the programmatic `ts.createProgram` API doesn't benefit from this.
+
+If you encounter spurious type errors during declaration generation that don't appear in `tsc` or your IDE, this is likely the cause. A workaround is to fix the offending type at the call site.
+
 # Potential errors
 
 es-build, which is essentially the basis for this whole thing, breaks reproducible builds as it includes the full path to a file as both a comment and a map key. To get around this we manually replace certain paths on build. There is a good chance this will not work for globally installed modules and will break certain hard coded strings.

package/bundles/EntryConfigInstance.d.ts

@@ -1,4 +1,4 @@
-import type { ResolvedEntryConfig, EntryConfig, CompleteEntryConfig } from "./types";
+import type { ResolvedEntryConfig, EntryConfig, CompleteEntryConfig } from "./types.ts";
 export declare class EntryConfigInstance {
     readonly config: ResolvedEntryConfig;
     readonly name: string;