@normed/bundle 4.7.1 → 4.8.2

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.8.0
+
+* MINOR: Add `webRoot` config for correct asset URL resolution when the web root is a subdirectory of `outdir`. Asset URLs in HTML are computed relative to the web root instead of the output directory. Also promotes `publicPath` and `assetNames` to top-level `bundle` config (old nested location still works but logs a deprecation warning).
+
 # 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.

package/README.md

@@ -194,50 +194,64 @@ This means these files referenced from your CSS/JS will be copied to the output
 
 ### 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:
+Control how static assets (images, fonts, media) are named and referenced in your output.
 
 ```json
 {
   "bundle": {
-    "baseConfig": {
-      "javascript": {
-        "esbuild": {
-          "publicPath": "https://cdn.example.com/assets"
-        }
-      }
-    }
+    "assetNames": "assets/[name]-[hash]",
+    "publicPath": "https://cdn.example.com"
   }
 }
 ```
 
-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`).
+- **`assetNames`** — Template for output filenames. Supports `[name]`, `[hash]`, `[ext]`, `[dir]`. Default: `[name]-[hash]`.
+- **`publicPath`** — URL prefix prepended to asset references in HTML and CSS. Useful for CDNs or when assets are served from a specific path.
 
 **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:
+The default `assetNames` 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.
+
+#### Serving from a subdirectory (`webRoot`)
+
+If your output has a subdirectory that serves as the web root (common when bundling both server and client code), set `webRoot` so asset URLs are computed relative to it:
 
 ```json
 {
   "bundle": {
-    "baseConfig": {
-      "javascript": {
-        "esbuild": {
-          "publicPath": "/static",
-          "assetNames": "assets/[name]-[hash]"
-        }
-      }
-    }
+    "webRoot": "public",
+    "assetNames": "public/assets/[name]-[hash]"
+  }
+}
+```
+
+```
+src/                              bundles/
+├─ public/                        ├─ public/
+│  ├─ index.static.pug    →      │  ├─ index.html
+│  ├─ logo.png             →     │  ├─ assets/logo-A1B2C3D4.png
+├─ worker.node.ts          →     ├─ worker.js
+```
+
+With `webRoot: "public"`, `index.html` references the logo as `/assets/logo-A1B2C3D4.png` — correct for a server serving `bundles/public/` at `/`.
+
+Without `webRoot`, the reference would incorrectly be `/assets/public/assets/logo-A1B2C3D4.png`.
+
+To host under a URL prefix, combine with `publicPath`:
+
+```json
+{
+  "bundle": {
+    "webRoot": "public",
+    "publicPath": "/myapp",
+    "assetNames": "public/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
+This produces URLs like `/myapp/assets/logo-A1B2C3D4.png`.
 
-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.
+> **Note:** These options can also be set under `baseConfig.javascript.esbuild` for backwards compatibility, but the top-level location is preferred.
 
 ### external CSS URLs