@normed/bundle 4.3.1 → 4.4.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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.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.
+
 # 4.3.1
 
 * MINOR: Fixes artefact check for building less files (resolves unexpected artefact / missing artefact).

package/README.md

@@ -57,6 +57,8 @@ Specify your configuration in your `package.json` by adding the `"bundle"` entry
 
 ```ts
 type EntryConfig = {
+  "entrypoint"?: boolean, 
+
   // When true or a string outputs bundle analysis files. When a string, uses that string to prefix analysis files
   "analyse"?: boolean | string,
   
@@ -81,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[]
+  }
 }
 ```
 
@@ -158,6 +167,49 @@ 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.
+
 ### analyse
 
 To get a report on bundle content and size enable analysis:
@@ -244,6 +296,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.

package/bundles/bin/cli.js

@@ -68637,7 +68637,7 @@ async function copy(from, to) {
   }
   await import_fs_extra2.default.promises.copyFile(from, to);
 }
-var contextModifiers = ["context"];
+var contextModifiers = ["context", "asset"];
 function __throw__(error) {
   throw error;
 }
@@ -68689,6 +68689,9 @@ var refineEntryConfig = makePartialRefinement({
       import_refinements2.refineString,
       refineESBuildOptions
     )
+  }),
+  css: makePartialRefinement({
+    externalUrls: (0, import_refinements2.refineArrayOf)(import_refinements2.refineString)
   })
 });
 var refinePackageJSONBuildConfig = makePartialRefinement({
@@ -69364,6 +69367,33 @@ var plugin3 = (options2) => {
 };
 var load_ts_js_default = plugin3;
 
+// pnp:/builds/normed/bundle/packages/bundle/src/esbuild-plugins/css_external_urls.ts
+function createCssExternalUrlsPlugin(patterns) {
+  const name3 = "css-external-urls";
+  const regexPatterns = patterns.map((pattern) => {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    const regexStr = "^" + escaped.replace(/\*/g, ".*") + "$";
+    return new RegExp(regexStr);
+  });
+  return {
+    name: name3,
+    setup(build2) {
+      build2.onResolve({ filter: /.*/ }, (args) => {
+        const path12 = args.path;
+        for (const regex of regexPatterns) {
+          if (regex.test(path12)) {
+            return {
+              path: path12,
+              external: true
+            };
+          }
+        }
+        return void 0;
+      });
+    }
+  };
+}
+
 // pnp:/builds/normed/bundle/packages/bundle/src/builders/esbuilder.ts
 var import_esbuild_plugin_pnp = __toESM(require_lib15());
 var ts = __toESM(require("typescript"));
@@ -69412,7 +69442,7 @@ var esbuilder = {
       const outdir = exampleFile.outfile.basedir;
       const indir = exampleFile.infile.basedir;
       const baseConfig = exampleFile.entryconfig.esbuild;
-      const expectingSourcemap = (baseConfig.sourcemap ?? true) && baseConfig.sourcemap !== "inline";
+      const expectingSourcemap = (baseConfig.sourcemap ?? true) && Boolean(baseConfig.sourcemap) && baseConfig.sourcemap !== "inline";
       const jsOutExt = baseConfig.format === "esm" ? "js" : "js";
       const promises = [];
       log_default.verbose("Base Config", JSON.stringify(baseConfig, null, 2));
@@ -69444,6 +69474,7 @@ var esbuilder = {
           ([k, v]) => `${v.entrypoint.infile.relative} -> ${k}`
         )
       );
+      const externalUrlsPlugin = exampleFile.entryconfig.css?.externalUrls?.length ? createCssExternalUrlsPlugin(exampleFile.entryconfig.css.externalUrls) : null;
       const finalConfig = {
         ...baseConfig,
         plugins: [
@@ -69451,6 +69482,7 @@ var esbuilder = {
           load_less_default,
           load_pug_default,
           load_ts_js_default({ sourceRelativeDirnameFilename: true, basedir: indir }),
+          ...externalUrlsPlugin ? [externalUrlsPlugin] : [],
           (0, import_esbuild_plugin_pnp.pnpPlugin)()
           // if running in yarn/other pnp env
         ],
@@ -69652,7 +69684,10 @@ var builders = {
   copy: copyBuilder
 };
 var defaultBuilders = [builders.es, builders.copy];
-function getBuilder(builders2, ext) {
+function getBuilder(builders2, ext, modifiers) {
+  if (modifiers?.includes("asset")) {
+    return copyBuilder;
+  }
   for (const builder of builders2) {
     for (const inExt of builder.inExt) {
       if (inExt instanceof RegExp && inExt.test(ext) || inExt === ext) {
@@ -70171,7 +70206,10 @@ var EntryConfigInstance = class _EntryConfigInstance {
       analyse: merged.analyse ?? absurd(),
       tsconfig: merged.typescript?.tsconfig ?? absurd(),
       declarations: merged.typescript?.declarations ?? absurd(),
-      esbuild: merged.javascript?.esbuild ?? absurd()
+      esbuild: merged.javascript?.esbuild ?? absurd(),
+      css: {
+        externalUrls: merged.css?.externalUrls ?? []
+      }
     };
     this.completed = complete;
     return complete;
@@ -70241,6 +70279,15 @@ var EntryConfigInstance = class _EntryConfigInstance {
             ...a.javascript?.esbuild,
             ...b.javascript?.esbuild
           }
+        },
+        css: {
+          ...a.css,
+          ...b.css,
+          // Merge external URLs arrays
+          externalUrls: [
+            ...a.css?.externalUrls ?? [],
+            ...b.css?.externalUrls ?? []
+          ]
         }
       };
     }
@@ -70302,7 +70349,11 @@ async function pathToEntrypoint(buildConfig, file, source) {
       `WARN: Determined "${infile.relative}" is not a file, but continuing on as though it is`
     );
   }
-  const builder = getBuilder(buildConfig.builders, infile.extension);
+  const builder = getBuilder(
+    buildConfig.builders,
+    infile.extension,
+    infile.modifiers
+  );
   if (!builder) {
     return new NoMatchingBuilder(infile.relative, infile.extension);
   }
@@ -70375,7 +70426,11 @@ async function discoveredEntrypoints(buildConfig) {
           parseModifiers: true,
           supportedModifiers: buildConfig.modifiers
         });
-        const builder = getBuilder(buildConfig.builders, infile.extension);
+        const builder = getBuilder(
+          buildConfig.builders,
+          infile.extension,
+          infile.modifiers
+        );
         if (builder === null) {
           return new NoMatchingBuilder(infile.relative, infile.extension);
         }
@@ -70464,6 +70519,10 @@ async function getBuildConfig(options2) {
         entrypoint: true,
         extends: "node"
       },
+      asset: {
+        entrypoint: true
+        // No extends - files with .asset modifier are copied verbatim
+      },
       web: {
         entrypoint: true,
         extends: "browser"
@@ -70518,7 +70577,23 @@ async function getBuildConfig(options2) {
           sourcemap: "external",
           platform: "neutral",
           loader: {
-            //             ".pug": "text",
+            // Default loaders for common asset types
+            ".png": "file",
+            ".jpg": "file",
+            ".jpeg": "file",
+            ".gif": "file",
+            ".webp": "file",
+            ".svg": "file",
+            ".ttf": "file",
+            ".otf": "file",
+            ".woff": "file",
+            ".woff2": "file",
+            ".eot": "file",
+            ".ico": "file",
+            ".mp4": "file",
+            ".webm": "file",
+            ".mp3": "file",
+            ".wav": "file"
           },
           minify: false,
           external: [],