@normed/bundle 4.3.2 → 4.5.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ 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.5.0
+
+* MINOR: Adds asset processing for pug entrypoints. Images, fonts, and other assets referenced in pug files are now hashed, copied to the output directory, and their paths rewritten automatically.
+* MINOR: Adds automatic pug-to-pug entrypoint discovery. When a pug file links to another pug file (e.g., `a(href="about.pug")`), the linked file is automatically built as an entrypoint and the href is rewritten to point to the output path.
+
+# 4.4.0
+
+* MINOR: Adds `css.externalUrls` configuration option for marking URL patterns as external in CSS files.
+* MINOR: Adds `createCssExternalUrlsPlugin` esbuild plugin.
+* MINOR: Adds the `asset` modifier for copying files verbatim without processing.
+* MINOR: Adds default file loaders for common asset types (images, fonts, media).
+* PATCH: Adds documentation for common pitfalls.
+
 # 4.3.2
 
 * MINOR: fixes map files being expected when no sourcemap value is set.

package/README.md

@@ -83,6 +83,13 @@ type EntryConfig = {
       "config"?: string | ESBuildConfig,
     }
   }
+
+  // Configuration specific to CSS processing
+  "css"?: {
+    // URL patterns to mark as external (not resolved at build time)
+    // Supports glob-style wildcards, e.g. ["/fonts/*", "/images/*"]
+    "externalUrls"?: string[]
+  }
 }
 ```
 
@@ -160,6 +167,79 @@ Any files you don't want to name with such a suffix can be added manually. To ad
 yarn bundle --entrypoint anchovies.ts --entrypoint pics/cartoons.png
 ```
 
+### asset modifier
+
+Use the `.asset` modifier to copy files verbatim without any processing. This is useful for pre-built CSS or JavaScript files that should not be processed by esbuild:
+
+```
+src/
+├─ vendor/
+│  ├─ legacy.asset.js      → bundles/vendor/legacy.js  (copied verbatim)
+│  ├─ styles.asset.css     → bundles/vendor/styles.css (copied verbatim)
+```
+
+This is particularly helpful for:
+- Third-party CSS/JS libraries with complex `url()` references
+- Pre-minified vendor files
+- Files with runtime paths that shouldn't be resolved at build time
+
+### default file loaders
+
+Common asset types are automatically configured to use esbuild's `file` loader:
+- Images: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`, `.ico`
+- Fonts: `.ttf`, `.otf`, `.woff`, `.woff2`, `.eot`
+- Media: `.mp4`, `.webm`, `.mp3`, `.wav`
+
+This means these files referenced from your CSS/JS will be copied to the output directory and their paths will be rewritten appropriately.
+
+### 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:
+
+```json
+{
+  "bundle": {
+    "baseConfig": {
+      "css": {
+        "externalUrls": ["/fonts/*", "/images/*", "https://*"]
+      }
+    }
+  }
+}
+```
+
+URL patterns support glob-style wildcards (`*`). URLs matching these patterns will be marked as external and left unchanged in the output CSS.
+
+### pug-to-pug linking
+
+When a pug file contains links to other pug files, those linked files are automatically discovered and built as entrypoints. The href attributes are rewritten to point to the compiled HTML output.
+
+```pug
+//- index.static.pug
+html
+  body
+    nav
+      a(href="about.pug") About Us
+      a(href="pages/contact.pug") Contact
+```
+
+This produces:
+```
+src/                          bundles/
+├─ index.static.pug    →     ├─ index.html (href rewritten to "about.html")
+├─ about.pug           →     ├─ about.html (auto-discovered)
+├─ pages/                    ├─ pages/
+   └─ contact.pug      →        └─ contact.html (auto-discovered)
+```
+
+Features:
+- **Recursive**: If `about.pug` links to `team.pug`, that gets built too
+- **Circular reference safe**: Files are only processed once
+- **Asset handling**: Images and other assets in discovered pug files are processed normally
+- **Warning on missing**: A warning is logged if a referenced pug file doesn't exist
+
+This works for all HTML attributes that can contain paths (href, src, data, poster, etc.).
+
 ### analyse
 
 To get a report on bundle content and size enable analysis:
@@ -246,6 +326,44 @@ import { verifyBuilder } from '@normed/bundle';
 
 This does not fully test your builder, but it does run some tests we have found helpful.
 
+# Common Pitfalls
+
+### Custom entrypoint modifiers not discovered
+
+**Problem**: You want to use a custom file suffix like `.worker.ts` but files aren't being discovered.
+
+**Cause**: Using `platformModifiers` in package.json. This is a CLI-only option, not a package.json config.
+
+**Solution**: Use `modifiers` with `entrypoint: true`:
+
+```json
+{
+  "bundle": {
+    "modifiers": {
+      "worker": {
+        "entrypoint": true,
+        "extends": "server"
+      }
+    }
+  }
+}
+```
+
+Now `*.worker.ts` files will be discovered and built with server platform settings.
+
+### No entrypoints found
+
+**Problem**: Build completes but reports "No entrypoints".
+
+**Cause**: Files must match a recognized pattern (`.static.*`, `.node.*`, `.web.*`, or custom modifiers with `entrypoint: true`).
+
+**Solution**: Either:
+1. Rename your file to use a recognized pattern (e.g., `index.static.ts`)
+2. Add a custom modifier in package.json (see above)
+3. Manually specify entrypoints: `"entrypoints": ["myfile.ts"]`
+
+Use `LOG_LEVEL=verbose yarn bundle` to see which patterns are being searched.
+
 # 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.