or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

asset-processing.md content-processing.md index.md minification.md runtime-utilities.md

tile.json

HTML Asset Processing

HTML Loader's asset processing system automatically detects and imports assets referenced in HTML attributes, converting them into webpack imports and generating appropriate module code.

Capabilities

Sources Configuration

Controls which HTML elements and attributes are processed for asset imports.

/**
 * Configure asset processing sources
 * @param sources - Boolean to enable/disable all processing, or detailed configuration object
 */
interface SourcesOptions {
  /** List of source definitions specifying which tags/attributes to process */
  list?: SourceDefinition[];
  /** Function to filter which URLs should be processed */
  urlFilter?: (attribute: string, value: string, resourcePath: string) => boolean;
  /** Whether to process content inside <noscript> tags */
  scriptingEnabled?: boolean;
}

interface SourceDefinition {
  /** HTML tag name to match (optional, defaults to all tags) */
  tag?: string;
  /** HTML attribute name to match */
  attribute: string;
  /** Type of processing to apply */
  type: "src" | "srcset";
  /** Optional filter function for fine-grained control */  
  filter?: (tag: string, attribute: string, attributes: string, resourcePath: string) => boolean;
}

Default Supported Elements:

audio:
```
src
```
embed:
```
src
```
img:
```
src
```
,
```
srcset
```
input:
```
src
```
link:
```
href
```
(with rel filtering),
```
imagesrcset
```
meta:
```
content
```
(with name/property filtering)
object:
```
data
```
script:
```
src
```
,
```
href
```
,
```
xlink:href
```
(with type filtering)
source:
```
src
```
,
```
srcset
```
track:
```
src
```
video:
```
poster
```
,
```
src
```
image (SVG):
```
xlink:href
```
,
```
href
```
use (SVG):
```
xlink:href
```
,
```
href
```

Usage Examples:

// Enable all default processing
{
  test: /\.html$/i,
  loader: "html-loader",
  options: {
    sources: true
  }
}

// Disable all processing
{
  test: /\.html$/i,
  loader: "html-loader",
  options: {
    sources: false
  }
}

// Custom configuration
{
  test: /\.html$/i,
  loader: "html-loader",
  options: {
    sources: {
      list: [
        // Include all defaults
        "...",
        // Add custom attribute processing
        {
          tag: "img",
          attribute: "data-src",
          type: "src"
        },
        {
          tag: "img", 
          attribute: "data-srcset",
          type: "srcset"
        }
      ],
      urlFilter: (attribute, value, resourcePath) => {
        // Skip PDF files
        if (/\.pdf$/i.test(value)) {
          return false;
        }
        return true;
      },
      scriptingEnabled: false
    }
  }
}

URL Filter Function

Provides fine-grained control over which URLs are processed for imports.

/**
 * Filter function to determine if a URL should be processed
 * @param attribute - The HTML attribute name containing the URL
 * @param value - The URL value from the attribute
 * @param resourcePath - Path to the current HTML file being processed
 * @returns true if the URL should be processed, false to leave it unchanged
 */
type UrlFilterFunction = (
  attribute: string,
  value: string, 
  resourcePath: string
) => boolean;

Usage Example:

{
  sources: {
    urlFilter: (attribute, value, resourcePath) => {
      // Skip external URLs
      if (/^https?:\/\//.test(value)) {
        return false;
      }
      
      // Skip specific file types
      if (/\.(pdf|doc|docx)$/i.test(value)) {
        return false;
      }
      
      // Skip URLs in specific files
      if (resourcePath.includes('/email-templates/')) {
        return false;
      }
      
      return true;
    }
  }
}

Source Type Processing

Different processing modes for HTML attributes.

/**
 * Process src-type attributes (single URL)
 * @param options - Processing options including URL value and context
 * @returns Array of source objects with processed URLs
 */
function srcType(options: ProcessingOptions): SourceResult[];

/**
 * Process srcset-type attributes (multiple URLs with descriptors)
 * @param options - Processing options including srcset value and context  
 * @returns Array of source objects with processed URLs
 */
function srcsetType(options: ProcessingOptions): SourceResult[];

interface ProcessingOptions {
  value: string;
  attribute: string;
  tag: string;
  valueStartOffset: number;
  attributeStartOffset: number;
  attributeEndOffset: number;
  html: string;
  isSupportDataURL: boolean;
  isSupportAbsoluteURL: boolean;
}

interface SourceResult {
  value: string;
  startOffset: number;
  endOffset: number;
}

Filter Functions

Built-in filter functions for common use cases.

/**
 * Filter script src attributes based on type attribute
 * @param tag - HTML tag name
 * @param attribute - HTML attribute name
 * @param attributes - All attributes of the element
 * @returns true if the script should be processed
 */
function scriptSrcFilter(tag: string, attribute: string, attributes: string): boolean;

/**
 * Filter link href attributes based on rel attribute
 * @param tag - HTML tag name  
 * @param attribute - HTML attribute name
 * @param attributes - All attributes of the element
 * @returns true if the link should be processed
 */
function linkHrefFilter(tag: string, attribute: string, attributes: string): boolean;

/**
 * Filter meta content attributes based on name/property attributes
 * @param tag - HTML tag name
 * @param attribute - HTML attribute name
 * @param attributes - All attributes of the element  
 * @returns true if the meta content should be processed
 */
function metaContentFilter(tag: string, attribute: string, attributes: string): boolean;

Disabling Processing with Comments

Use HTML comments to disable processing for specific elements.

<!-- Disable processing for the next img tag -->
<!-- webpackIgnore: true -->
<img src="external-image.png" alt="Not processed" />

<!-- Disable processing for img with srcset -->
<!-- webpackIgnore: true -->
<img srcset="image-1x.png 1x, image-2x.png 2x" src="image-1x.png" alt="Not processed" />

<!-- Disable processing for link -->
<!-- webpackIgnore: true -->
<link rel="stylesheet" href="external-styles.css" />

URL Processing Rules

HTML Loader determines which URLs to process based on several criteria:

/**
 * Check if a URL should be processed by webpack
 * @param url - The URL to check
 * @param options - Processing options
 * @returns true if the URL should be processed as a webpack module
 */
function isURLRequestable(url: string, options: {
  isSupportDataURL?: boolean;
  isSupportAbsoluteURL?: boolean;
}): boolean;

Processing Rules:

Relative URLs:
```
./image.png
```
,
```
../assets/logo.svg
```
→ ✅ Processed
Root-relative URLs:
```
/images/hero.jpg
```
→ ✅ Processed (with resolve.roots configuration)
Protocol-relative URLs:
```
//cdn.example.com/image.png
```
→ ❌ Not processed
Absolute URLs:
```
https://example.com/image.png
```
→ ❌ Not processed (unless isSupportAbsoluteURL enabled)
Data URLs:
```
data:image/png;base64,...
```
→ ✅ Processed (if isSupportDataURL enabled)
File URLs:
```
file:///path/to/file.png
```
→ ✅ Processed
Template expressions:
```
<%= imageUrl %>
```
,
```
{{imageUrl}}
```
→ ❌ Not processed

Advanced URL Configuration:

// Enable data URL processing
{
  sources: {
    // This enables data URL processing via esModule option
  },
  esModule: true
}

// Configure for absolute URL support (requires webpack experiments.buildHttp)
module.exports = {
  experiments: {
    buildHttp: true
  },
  module: {
    rules: [
      {
        test: /\.html$/i,
        loader: "html-loader"
      }
    ]
  }
};