feat: transform assets in CSS and fix hash recalculation

Author: bashmish

package-lock.json

@@ -49,7 +49,8 @@
     "html-minifier-terser": "^7.1.0",
     "lightningcss": "^1.24.0",
     "parse5": "^6.0.1",
-    "picomatch": "^2.2.2"
+    "picomatch": "^2.2.2",
+    "xxhash-wasm": "^1.1.0"
   },
   "devDependencies": {
     "@prettier/sync": "^0.6.1",

packages/rollup-plugin-html/package.json

@@ -4,40 +4,39 @@ import { toBrowserPath } from './utils.js';
 
 /**
  * Regular expression to match asset URL placeholders in CSS content.
- * Captures the reference ID like "abc123" from placeholders like "__ROLLUP_ASSET_URL_abc123__".
- * Note: Rollup reference IDs can contain alphanumeric characters, underscores, and $ (base-64-like encoding).
+ * Captures the hashes encoded as HEX strings like "abc123" from placeholders like "__ROLLUP_ASSET_URL_abc123__".
  */
-const ASSET_URL_PLACEHOLDER_REGEX = /__ROLLUP_ASSET_URL_([a-zA-Z0-9_$]+)__/g;
+const ASSET_URL_PLACEHOLDER_REGEX = /__ROLLUP_ASSET_URL_([a-f0-9]+)__/g;
 
 /**
- * Creates a placeholder string for the given reference ID.
- * @param refId - The Rollup file reference ID
+ * Creates a placeholder string for the given hash.
+ *
+ * @param hash - Hash encoded as a HEX string (e.g. "abc123")
  * @returns Placeholder string like "__ROLLUP_ASSET_URL_abc123__"
  */
-export function createAssetPlaceholder(refId: string): string {
-  return `__ROLLUP_ASSET_URL_${refId}__`;
+export function createAssetPlaceholder(hash: string): string {
+  return `__ROLLUP_ASSET_URL_${hash}__`;
 }
 
 /**
  * Replaces all asset URL placeholders in CSS content with resolved paths.
- * Anything after the placeholder (#id, ?queryString) is preserved naturally.
  *
  * @param cssContent - The CSS content with placeholders
- * @param resolver - Function that resolves a reference ID to the final path
+ * @param resolver - Function that resolves a hash to the final path
  * @returns CSS content with placeholders replaced
  */
 export function replacePlaceholders(
   cssContent: string,
-  resolver: (refId: string) => string | undefined,
+  resolver: (hash: string) => string | undefined,
 ): string {
-  return cssContent.replace(ASSET_URL_PLACEHOLDER_REGEX, (match, refId) => {
-    const resolvedPath = resolver(refId);
+  return cssContent.replace(ASSET_URL_PLACEHOLDER_REGEX, (match, hash) => {
+    const resolvedPath = resolver(hash);
     return resolvedPath ?? match;
   });
 }
 
 /**
- * Calculates the path from a CSS file to a referenced asset.
+ * Calculates the path from a CSS file to a referenced asset in the output.
  * If publicPath is provided, returns an absolute path. Otherwise returns a relative path.
  *
  * @param cssFilePath - The CSS file's path in the bundle (e.g. 'styles/main.css')
@@ -50,44 +49,39 @@ export function calculateRelativePath(
   assetFilePath: string,
   publicPath?: string,
 ): string {
-  // If publicPath is provided, return an absolute path
   if (publicPath) {
-    return toBrowserPath(`${publicPath}${assetFilePath}`);
+    return toBrowserPath(path.join(publicPath, assetFilePath));
   }
 
-  // Otherwise, calculate relative path
   const cssDir = path.dirname(cssFilePath);
   const relativePath = path.relative(cssDir, assetFilePath);
-
-  // Convert to browser-style forward slashes
   return toBrowserPath(relativePath);
 }
 
 /**
  * Processes all CSS files in the bundle, replacing placeholders with resolved paths.
  *
- * @param {PluginContext} pluginContext - the Rollup plugin context
- * @param {OutputBundle} bundle - the Rollup output bundle
+ * @param {PluginContext} pluginContext - The Rollup plugin context
+ * @param {OutputBundle} bundle - The Rollup output bundle
+ * @param {Record<string, { ref: string }>} assetsInCssByHash - Map of asset hashes to their Rollup refs for assets found in CSS
  * @param {string} [publicPath] - Optional public path prefix for absolute URLs (e.g. '/static/')
  */
 export function processCssAssets(
   pluginContext: PluginContext,
   bundle: OutputBundle,
+  assetsInCssByHash: Record<string, { ref: string }>,
   publicPath?: string,
 ): void {
-  for (const [fileName, asset] of Object.entries(bundle)) {
-    if (asset.type !== 'asset' || !fileName.endsWith('.css')) continue;
+  for (const [filePath, asset] of Object.entries(bundle)) {
+    if (asset.type !== 'asset' || !filePath.endsWith('.css')) continue;
 
-    const content =
+    const cssContent =
       typeof asset.source === 'string' ? asset.source : Buffer.from(asset.source).toString('utf-8');
 
-    const resolvedContent = replacePlaceholders(content, (refId: string) => {
-      try {
-        const assetFileName = pluginContext.getFileName(refId);
-        return calculateRelativePath(fileName, assetFileName, publicPath);
-      } catch {
-        pluginContext.error(`Could not resolve CSS asset reference '${refId}' in ${fileName}`);
-      }
+    const resolvedContent = replacePlaceholders(cssContent, (hash: string) => {
+      const ref = assetsInCssByHash[hash]!.ref;
+      const assetFilePath = pluginContext.getFileName(ref);
+      return calculateRelativePath(filePath, assetFilePath, publicPath);
     });
 
     asset.source = resolvedContent;

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

@@ -2,6 +2,7 @@ import { PluginContext } from 'rollup';
 import path from 'path';
 import { bundleAsync, transform } from 'lightningcss';
 import fs from 'fs';
+import xxhash from 'xxhash-wasm';
 
 import { InputAsset, InputData } from '../input/InputData';
 import { createAssetPicomatchMatcher } from '../assets/utils.js';
@@ -11,6 +12,7 @@ import { createAssetPlaceholder } from './css.js';
 export interface EmittedAssets {
   static: Map<string, string>;
   hashed: Map<string, string>;
+  assetsInCssByHash: Record<string, { ref: string }>;
 }
 
 const allowedFileExtensions = [
@@ -40,6 +42,8 @@ export async function emitAssets(
   inputs: InputData[],
   options: RollupPluginHTMLOptions,
 ) {
+  const { create64 } = await xxhash();
+
   const extractAssets = options.extractAssets ?? true;
   const bundleCss = options.bundleCss ?? true;
   const minifyCss = options.minifyCss ?? false;
@@ -56,9 +60,28 @@ export async function emitAssets(
       transforms.push(options.transformAsset);
     }
   }
+
+  async function getTransformedAsset(content: Buffer, filePath: string): Promise<Buffer> {
+    let source: Buffer = content;
+    for (const transform of transforms) {
+      const result = await transform(content, filePath);
+      if (result != null) {
+        source = typeof result === 'string' ? Buffer.from(result, 'utf-8') : result;
+      }
+    }
+    return source;
+  }
+
   const staticAssets: InputAsset[] = [];
   const hashedAssets: InputAsset[] = [];
 
+  let assetsInCssCounter = 0;
+  const assetsInCssByAbsPath: Record<
+    string,
+    { tempPlaceholder: string; ref?: string; outputPath?: string; hash?: string }
+  > = {};
+  const assetsInCssByHash: Record<string, { ref: string }> = {};
+
   for (const input of inputs) {
     for (const asset of input.assets) {
       if (asset.hashed) {
@@ -75,20 +98,10 @@ export async function emitAssets(
   for (const asset of allAssets) {
     const map = asset.hashed ? emittedHashedAssets : emittedStaticAssets;
     if (!map.has(asset.filePath)) {
-      let source: Buffer = asset.content;
-
-      // run user's transform functions
-      for (const transform of transforms) {
-        const result = await transform(asset.content, asset.filePath);
-        if (result != null) {
-          source = typeof result === 'string' ? Buffer.from(result, 'utf-8') : result;
-        }
-      }
-
+      let source = await getTransformedAsset(asset.content, asset.filePath);
       let ref: string;
       let basename = path.basename(asset.filePath);
       const isExternal = createAssetPicomatchMatcher(options.externalAssets);
-      const emittedAssets = new Map<string, { filePath: string; refId: string }>();
       if (asset.hashed) {
         if (basename.endsWith('.css') && extractAssets) {
           const { code } = await (bundleCss ? bundleAsync : transform)({
@@ -99,48 +112,79 @@ export async function emitAssets(
               Url: url => {
                 // Support foo.svg#bar
                 // 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('#');
+                const [srcAssetPath, srcAssetId] = url.url.split('#');
 
-                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);
+                if (shouldHandleAsset(srcAssetPath) && !isExternal(srcAssetPath)) {
+                  const assetAbsPath = path.resolve(path.dirname(asset.filePath), srcAssetPath);
 
-                  let emittedAsset = emittedAssets.get(assetLocation);
+                  let assetInCss = assetsInCssByAbsPath[assetAbsPath];
 
-                  if (!emittedAsset) {
+                  if (!assetInCss) {
                     // Avoid duplicates
-                    const basename = path.basename(filePath);
-                    const fileRef = this.emitFile({
-                      type: 'asset',
-                      name: extractAssetsLegacyCss ? `assets/${basename}` : basename,
-                      originalFileName: assetLocation,
-                      source: assetContent,
-                    });
-                    const emittedAssetFilepath = this.getFileName(fileRef);
-                    emittedAsset = {
-                      filePath: emittedAssetFilepath,
-                      refId: fileRef,
+                    assetsInCssCounter++;
+                    assetInCss = {
+                      tempPlaceholder: createAssetPlaceholder(assetsInCssCounter.toString()),
+                      ref: undefined,
+                      hash: undefined,
                     };
-                    emittedAssets.set(assetLocation, emittedAsset);
+                    assetsInCssByAbsPath[assetAbsPath] = assetInCss;
                   }
 
-                  if (extractAssetsLegacyCss) {
-                    const emittedAssetBasename = path.basename(emittedAsset.filePath);
-                    url.url = `assets/${emittedAssetBasename}`;
-                  } else {
-                    url.url = createAssetPlaceholder(emittedAsset.refId);
-                  }
-
-                  if (idRef) {
-                    url.url = `${url.url}#${idRef}`;
-                  }
+                  url.url = srcAssetId
+                    ? `${assetInCss.tempPlaceholder}#${srcAssetId}`
+                    : assetInCss.tempPlaceholder;
                 }
+
                 return url;
               },
             },
           });
-          const codeBuffer = Buffer.from(code);
+
+          let codeString = code.toString();
+
+          for (const assetInCssAbsPath of Object.keys(assetsInCssByAbsPath)) {
+            const assetInCss = assetsInCssByAbsPath[assetInCssAbsPath];
+
+            if (!assetInCss.ref) {
+              const basename = path.basename(assetInCssAbsPath);
+              const content = await fs.promises.readFile(assetInCssAbsPath);
+              const transformedContent = await getTransformedAsset(content, assetInCssAbsPath);
+              const ref = this.emitFile({
+                type: 'asset',
+                name: extractAssetsLegacyCss ? `assets/${basename}` : basename,
+                originalFileName: assetInCssAbsPath,
+                source: transformedContent,
+              });
+              assetInCss.ref = ref;
+              assetInCss.outputPath = this.getFileName(ref);
+              if (!extractAssetsLegacyCss) {
+                assetInCss.hash = create64()
+                  .update(transformedContent)
+                  .update('\0')
+                  .update(assetInCss.outputPath)
+                  .digest()
+                  .toString(16)
+                  .padStart(16, '0');
+              }
+            }
+
+            if (extractAssetsLegacyCss) {
+              const outputName = path.basename(assetInCss.outputPath!);
+              codeString = codeString.replaceAll(
+                assetInCss.tempPlaceholder,
+                `assets/${outputName}`,
+              );
+            } else {
+              const hash = assetInCss.hash!;
+              assetsInCssByHash[hash] = { ref: assetInCss.ref };
+              codeString = codeString.replaceAll(
+                assetInCss.tempPlaceholder,
+                createAssetPlaceholder(hash),
+              );
+            }
+          }
+
+          const codeBuffer = Buffer.from(codeString);
           if (!asset.content.equals(codeBuffer)) {
             source = codeBuffer;
           }
@@ -169,5 +213,5 @@ export async function emitAssets(
     }
   }
 
-  return { static: emittedStaticAssets, hashed: emittedHashedAssets };
+  return { static: emittedStaticAssets, hashed: emittedHashedAssets, assetsInCssByHash };
 }

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

@@ -142,7 +142,7 @@ export function rollupPluginHTML(pluginOptions: RollupPluginHTMLOptions = {}): R
 
       const emittedAssets = await emitAssets.call(this, inputs, pluginOptions);
 
-      processCssAssets(this, bundle, pluginOptions.publicPath);
+      processCssAssets(this, bundle, emittedAssets.assetsInCssByHash, pluginOptions.publicPath);
 
       const outputs = await createHTMLOutput({
         outputDir: path.resolve(options.dir),
@@ -204,7 +204,12 @@ export function rollupPluginHTML(pluginOptions: RollupPluginHTMLOptions = {}): R
 
               const emittedAssets = await emitAssets.call(this, inputs, pluginOptions);
 
-              processCssAssets(this, bundle, pluginOptions.publicPath);
+              processCssAssets(
+                this,
+                bundle,
+                emittedAssets.assetsInCssByHash,
+                pluginOptions.publicPath,
+              );
 
               const outputs = await createHTMLOutput({
                 outputDir: path.resolve(options.dir),