feat(rollup-plugin-html): glob patterns exclusion for external assets

.changeset/nervous-bugs-rhyme.md

@@ -0,0 +1,5 @@
+---
+'@web/rollup-plugin-html': minor
+---
+
+glob patterns exclusion for external assets

docs/docs/building/rollup-plugin-html.md

@@ -362,6 +362,8 @@ export interface RollupPluginHTMLOptions {
   transformHtml?: TransformHtmlFunction | TransformHtmlFunction[];
   /** Whether to extract and bundle assets referenced in HTML. Defaults to true. */
   extractAssets?: boolean;
+  /** Whether to ignore assets referenced in HTML and CSS with glob patterns. */
+  externalAssets?: string | string[];
   /** Define a full absolute url to your site (e.g. https://domain.com) */
   absoluteBaseUrl?: string;
   /** Whether to set full absolute urls for ['meta[property=og:image]', 'link[rel=canonical]', 'meta[property=og:url]'] or not. Requires a absoluteBaseUrl to be set. Default to true. */

packages/rollup-plugin-html/package.json

@@ -48,10 +48,12 @@
     "glob": "^10.0.0",
     "html-minifier-terser": "^7.1.0",
     "lightningcss": "^1.24.0",
-    "parse5": "^6.0.1"
+    "parse5": "^6.0.1",
+    "picomatch": "^2.2.2"
   },
   "devDependencies": {
     "@types/html-minifier-terser": "^7.0.0",
+    "@types/picomatch": "^2.2.1",
     "rollup": "^4.4.0"
   }
 }

packages/rollup-plugin-html/src/RollupPluginHTMLOptions.ts

@@ -29,6 +29,8 @@ export interface RollupPluginHTMLOptions {
   transformHtml?: TransformHtmlFunction | TransformHtmlFunction[];
   /** Whether to extract and bundle assets referenced in HTML. Defaults to true. */
   extractAssets?: boolean;
+  /** Whether to ignore assets referenced in HTML and CSS with glob patterns. */
+  externalAssets?: string | string[];
   /** Define a full absolute url to your site (e.g. https://domain.com) */
   absoluteBaseUrl?: string;
   /** Whether to set full absolute urls for ['meta[property=og:image]', 'link[rel=canonical]', 'meta[property=og:url]'] or not. Requires a absoluteBaseUrl to be set. Default to true. */

packages/rollup-plugin-html/src/assets/utils.ts

@@ -1,5 +1,6 @@
 import { Document, Element } from 'parse5';
 import path from 'path';
+import picomatch from 'picomatch';
 import { findElements, getTagName, getAttribute } from '@web/parse5-utils';
 import { createError } from '../utils.js';
 import { serialize } from 'v8';
@@ -143,3 +144,11 @@ export function getSourcePaths(node: Element) {
 export function findAssets(document: Document) {
   return findElements(document, isAsset);
 }
+
+// picomatch follows glob spec and requires "./" to be removed for the matcher to work
+// it is safe, because with or without it resolves to the same file
+// read more: https://github.com/micromatch/picomatch/issues/77
+const removeLeadingSlash = (str: string) => (str.startsWith('./') ? str.slice(2) : str);
+export function createAssetPicomatchMatcher(glob?: string | string[]) {
+  return picomatch(glob || [], { format: removeLeadingSlash });
+}

packages/rollup-plugin-html/src/input/extract/extractAssets.ts

@@ -7,23 +7,28 @@ import {
   getSourcePaths,
   isHashedAsset,
   resolveAssetFilePath,
+  createAssetPicomatchMatcher,
 } from '../../assets/utils.js';
 
 export interface ExtractAssetsParams {
   document: Document;
   htmlFilePath: string;
   htmlDir: string;
   rootDir: string;
+  externalAssets?: string | string[];
   absolutePathPrefix?: string;
 }
 
 export function extractAssets(params: ExtractAssetsParams): InputAsset[] {
   const assetNodes = findAssets(params.document);
   const allAssets: InputAsset[] = [];
+  const isExternal = createAssetPicomatchMatcher(params.externalAssets);
 
   for (const node of assetNodes) {
     const sourcePaths = getSourcePaths(node);
     for (const sourcePath of sourcePaths) {
+      if (isExternal(sourcePath)) continue;
+
       const filePath = resolveAssetFilePath(
         sourcePath,
         params.htmlDir,

packages/rollup-plugin-html/src/input/extract/extractModulesAndAssets.ts

@@ -8,11 +8,12 @@ export interface ExtractParams {
   htmlFilePath: string;
   rootDir: string;
   extractAssets: boolean;
+  externalAssets?: string | string[];
   absolutePathPrefix?: string;
 }
 
 export function extractModulesAndAssets(params: ExtractParams) {
-  const { html, htmlFilePath, rootDir, absolutePathPrefix } = params;
+  const { html, htmlFilePath, rootDir, externalAssets, absolutePathPrefix } = params;
   const htmlDir = path.dirname(htmlFilePath);
   const document = parse(html);
 
@@ -24,7 +25,14 @@ export function extractModulesAndAssets(params: ExtractParams) {
     absolutePathPrefix,
   });
   const assets = params.extractAssets
-    ? extractAssets({ document, htmlDir, htmlFilePath, rootDir, absolutePathPrefix })
+    ? extractAssets({
+        document,
+        htmlDir,
+        htmlFilePath,
+        rootDir,
+        externalAssets,
+        absolutePathPrefix,
+      })
     : [];
 
   // turn mutated AST back to a string

packages/rollup-plugin-html/src/input/getInputData.ts

@@ -31,17 +31,20 @@ export interface CreateInputDataParams {
   rootDir: string;
   filePath?: string;
   extractAssets: boolean;
+  externalAssets?: string | string[];
   absolutePathPrefix?: string;
 }
 
 function createInputData(params: CreateInputDataParams): InputData {
-  const { name, html, rootDir, filePath, extractAssets, absolutePathPrefix } = params;
+  const { name, html, rootDir, filePath, extractAssets, externalAssets, absolutePathPrefix } =
+    params;
   const htmlFilePath = filePath ? filePath : path.resolve(rootDir, name);
   const result = extractModulesAndAssets({
     html,
     htmlFilePath,
     rootDir,
     extractAssets,
+    externalAssets,
     absolutePathPrefix,
   });
 
@@ -63,6 +66,7 @@ export function getInputData(
     rootDir = process.cwd(),
     flattenOutput,
     extractAssets = true,
+    externalAssets,
     absolutePathPrefix,
     exclude: ignore,
   } = pluginOptions;
@@ -77,6 +81,7 @@ export function getInputData(
         html: input.html,
         rootDir,
         extractAssets,
+        externalAssets,
         absolutePathPrefix,
       });
       result.push(data);
@@ -97,6 +102,7 @@ export function getInputData(
           rootDir,
           filePath,
           extractAssets,
+          externalAssets,
           absolutePathPrefix,
         });
         result.push(data);

packages/rollup-plugin-html/src/output/emitAssets.ts

@@ -4,6 +4,7 @@ import { transform } from 'lightningcss';
 import fs from 'fs';
 
 import { InputAsset, InputData } from '../input/InputData';
+import { createAssetPicomatchMatcher } from '../assets/utils.js';
 import { RollupPluginHTMLOptions, TransformAssetFunction } from '../RollupPluginHTMLOptions';
 
 export interface EmittedAssets {
@@ -81,6 +82,7 @@ export async function emitAssets(
 
       let ref: string;
       let basename = path.basename(asset.filePath);
+      const isExternal = createAssetPicomatchMatcher(options.externalAssets);
       const emittedExternalAssets = new Map();
       if (asset.hashed) {
         if (basename.endsWith('.css') && options.bundleAssetsFromCss) {
@@ -95,7 +97,7 @@ export async function emitAssets(
                 // https://www.w3.org/TR/html4/types.html#:~:text=ID%20and%20NAME%20tokens%20must,tokens%20defined%20by%20other%20attributes.
                 const [filePath, idRef] = url.url.split('#');
 
-                if (shouldHandleAsset(filePath)) {
+                if (shouldHandleAsset(filePath) && !isExternal(filePath)) {
                   // Read the asset file, get the asset from the source location on the FS using asset.filePath
                   const assetLocation = path.resolve(path.dirname(asset.filePath), filePath);
                   const assetContent = fs.readFileSync(assetLocation);

packages/rollup-plugin-html/src/output/getOutputHTML.ts

@@ -53,6 +53,7 @@ export async function getOutputHTML(params: GetOutputHTMLParams) {
       outputDir,
       rootDir,
       emittedAssets,
+      externalAssets: pluginOptions.externalAssets,
       absolutePathPrefix,
       publicPath: pluginOptions.publicPath,
     });

packages/rollup-plugin-html/src/output/injectedUpdatedAssetPaths.ts

@@ -8,6 +8,7 @@ import {
   getSourcePaths,
   isHashedAsset,
   resolveAssetFilePath,
+  createAssetPicomatchMatcher,
 } from '../assets/utils.js';
 import { InputData } from '../input/InputData.js';
 import { createError } from '../utils.js';
@@ -20,6 +21,7 @@ export interface InjectUpdatedAssetPathsArgs {
   outputDir: string;
   rootDir: string;
   emittedAssets: EmittedAssets;
+  externalAssets?: string | string[];
   publicPath?: string;
   absolutePathPrefix?: string;
 }
@@ -42,14 +44,18 @@ export function injectedUpdatedAssetPaths(args: InjectUpdatedAssetPathsArgs) {
     outputDir,
     rootDir,
     emittedAssets,
+    externalAssets,
     publicPath = './',
     absolutePathPrefix,
   } = args;
   const assetNodes = findAssets(document);
+  const isExternal = createAssetPicomatchMatcher(externalAssets);
 
   for (const node of assetNodes) {
     const sourcePaths = getSourcePaths(node);
     for (const sourcePath of sourcePaths) {
+      if (isExternal(sourcePath)) continue;
+
       const htmlFilePath = input.filePath ? input.filePath : path.join(rootDir, input.name);
       const htmlDir = path.dirname(htmlFilePath);
       const filePath = resolveAssetFilePath(sourcePath, htmlDir, rootDir, absolutePathPrefix);

packages/rollup-plugin-html/test/fixtures/assets/styles-with-referenced-assets.css

@@ -0,0 +1,15 @@
+#a1 {
+  background-image: url('image-a.png');
+}
+
+#a2 {
+  background-image: url('image-a.svg');
+}
+
+#d1 {
+  background-image: url('./image-d.png');
+}
+
+#d2 {
+  background-image: url('./image-d.svg');
+}

packages/rollup-plugin-html/test/rollup-plugin-html.test.ts

@@ -1216,6 +1216,97 @@ describe('rollup-plugin-html', () => {
 
 #h {
   background-image: url("assets/star-H06WHrYy.avif");
+}`.trim(),
+    );
+  });
+
+  it('allows to exclude external assets usign a glob pattern', async () => {
+    const config = {
+      plugins: [
+        rollupPluginHTML({
+          input: {
+            html: `<html>
+<head>
+<link rel="apple-touch-icon" sizes="180x180" href="./image-a.png" />
+<link rel="icon" type="image/png" sizes="32x32" href="image-d.png" />
+<link rel="manifest" href="./webmanifest.json" />
+<link rel="mask-icon" href="./image-a.svg" color="#3f93ce" />
+<link rel="mask-icon" href="image-d.svg" color="#3f93ce" />
+<link rel="stylesheet" href="./styles-with-referenced-assets.css" />
+<link rel="stylesheet" href="./foo/x.css" />
+<link rel="stylesheet" href="foo/bar/y.css" />
+</head>
+<body>
+<img src="./image-d.png" />
+<div>
+<img src="./image-d.svg" />
+</div>
+</body>
+</html>`,
+          },
+          bundleAssetsFromCss: true,
+          externalAssets: ['**/foo/**/*', '*.svg'],
+          rootDir: path.join(__dirname, 'fixtures', 'assets'),
+        }),
+      ],
+    };
+
+    const bundle = await rollup(config);
+    const { output } = await bundle.generate(outputConfig);
+
+    expect(output.length).to.equal(8);
+
+    const expectedAssets = [
+      'assets/image-a.png',
+      'assets/image-d.png',
+      'styles-with-referenced-assets.css',
+      'image-a.png',
+      'image-d.png',
+      'webmanifest.json',
+    ];
+
+    for (const name of expectedAssets) {
+      const asset = getAsset(output, name);
+      expect(asset).to.exist;
+      expect(asset.source).to.exist;
+    }
+
+    const outputHtml = getAsset(output, 'index.html').source;
+    expect(outputHtml).to.include(
+      '<link rel="apple-touch-icon" sizes="180x180" href="assets/image-a.png">',
+    );
+    expect(outputHtml).to.include(
+      '<link rel="icon" type="image/png" sizes="32x32" href="assets/image-d.png">',
+    );
+    expect(outputHtml).to.include('<link rel="manifest" href="assets/webmanifest.json">');
+    expect(outputHtml).to.include('<link rel="mask-icon" href="./image-a.svg" color="#3f93ce">');
+    expect(outputHtml).to.include('<link rel="mask-icon" href="image-d.svg" color="#3f93ce">');
+    expect(outputHtml).to.include(
+      '<link rel="stylesheet" href="assets/styles-with-referenced-assets-NuwIw8gN.css">',
+    );
+    expect(outputHtml).to.include('<link rel="stylesheet" href="./foo/x.css">');
+    expect(outputHtml).to.include('<link rel="stylesheet" href="foo/bar/y.css">');
+    expect(outputHtml).to.include('<img src="assets/assets/image-d-y8_AQMDl.png">');
+    expect(outputHtml).to.include('<img src="./image-d.svg">');
+
+    const rewrittenCss = getAsset(output, 'styles-with-referenced-assets.css')
+      .source.toString()
+      .trim();
+    expect(rewrittenCss).to.equal(
+      `#a1 {
+  background-image: url("assets/image-a-Mr5Lb2jQ.png");
+}
+
+#a2 {
+  background-image: url("image-a.svg");
+}
+
+#d1 {
+  background-image: url("assets/image-d-y8_AQMDl.png");
+}
+
+#d2 {
+  background-image: url("./image-d.svg");
 }`.trim(),
     );
   });