or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-parcel--transformer-html

Parcel transformer plugin for HTML files that handles parsing, dependency extraction, and asset transformation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@parcel/transformer-html@2.15.x

To install, run

npx @tessl/cli install tessl/npm-parcel--transformer-html@2.15.0

index.mddocs/

Parcel HTML Transformer

Parcel HTML Transformer is a specialized transformer plugin for the Parcel bundler that processes HTML files (including .htm and .xhtml) to extract dependencies, transform HTML content, and integrate with the Parcel asset pipeline. It leverages Rust-based HTML parsing for performance and accuracy.

Package Information

  • Package Name: @parcel/transformer-html
  • Package Type: npm
  • Language: JavaScript (Flow-typed)
  • Installation: Automatically installed as part of Parcel 2.x
  • Parcel Version: 2.15.3+

Core Imports

This package is designed to be used as a Parcel plugin and is not typically imported directly. However, if needed:

const HTMLTransformer = require("@parcel/transformer-html");

For ES modules:

import HTMLTransformer from "@parcel/transformer-html";

Basic Usage

This transformer is automatically used by Parcel when processing HTML files. No manual configuration is required in most cases. Simply include HTML files in your project:

<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
  <link rel="stylesheet" href="./styles.css">
</head>
<body>
  <div id="app"></div>
  <script src="./main.js"></script>
</body>
</html>

The transformer will automatically:

  • Process the HTML content through Rust-based parsing
  • Extract dependencies (CSS files, JavaScript modules, images, etc.)
  • Handle asset transformation and bundling
  • Support Hot Module Replacement (HMR) when enabled

Capabilities

HTML File Processing

Processes HTML files through Parcel's transformation pipeline with automatic dependency extraction and asset handling.

/**
 * Default export: Configured Transformer instance for HTML processing
 * This is the main export used by Parcel's plugin system
 */
export default Transformer;

/**
 * Transformer configuration object
 */
interface TransformerConfig {
  transform(context: TransformContext): Promise<Array<TransformerResult>>;
}

interface TransformContext {
  /** The HTML asset being transformed */
  asset: MutableAsset;
  /** Parcel build options including HMR settings */
  options: PluginOptions;
}

File Type Support

The transformer handles multiple HTML-related file types with appropriate processing.

/**
 * Supported file extensions:
 * - .html: Standard HTML files
 * - .htm: Converted to .html type during processing
 * - .xhtml: Processed with XML parsing mode enabled
 */
type SupportedExtensions = '.html' | '.htm' | '.xhtml';

Asset Processing Behavior

All HTML assets processed by this transformer receive specific bundle configuration.

/**
 * Bundle behavior applied to HTML assets
 * 'isolated' ensures HTML files are processed in separate bundles
 */
type BundleBehavior = 'isolated';

Transformation Process

The core transformation leverages Rust-based HTML parsing for performance and accuracy.

/**
 * Rust-based HTML transformation function (from @parcel/rust)
 * Called internally by the transformer
 */
function transformHtml(options: HtmlTransformOptions): HtmlTransformResult;

interface HtmlTransformOptions {
  /** HTML content as Buffer */
  code: Buffer;
  /** Path to the HTML file */
  filePath: string;
  /** Enable XML parsing for .xhtml files */
  xml: boolean;
  /** Parcel environment configuration converted to Rust format */
  env: RustEnvironment;
  /** Enable HMR support */
  hmr: boolean;
}

interface HtmlTransformResult {
  /** Transformed HTML code */
  code: Buffer;
  /** Extracted dependencies (CSS, JS, images, etc.) */
  dependencies: RustDependency[];
  /** Additional assets generated during transformation */
  assets: RustAsset[];
  /** Any errors encountered during transformation */
  errors: Array<Diagnostic>;
}

Error Handling

The transformer provides comprehensive error handling with detailed diagnostics.

/**
 * Error thrown when HTML transformation fails
 * Uses Parcel's diagnostic system for detailed error reporting
 */
class ThrowableDiagnostic extends Error {
  constructor(options: { diagnostic: Array<Diagnostic> });
}

interface Diagnostic {
  /** Error message */
  message: string;
  /** File location information */
  location?: SourceLocation;
  /** Additional error context */
  hints?: string[];
}

Types

Core Transformation Types

/**
 * Parcel Asset interface for HTML files
 */
interface MutableAsset {
  /** Asset type (.html, .htm, .xhtml) */
  type: string;
  /** File path of the asset */
  filePath: string;
  /** Asset content as Buffer */
  getBuffer(): Promise<Buffer>;
  /** Set transformed content */
  setBuffer(content: Buffer): void;
  /** Add dependency discovered during transformation */
  addDependency(dependency: DependencyOptions): void;
  /** Bundle behavior setting */
  bundleBehavior: BundleBehavior;
  /** Environment configuration */
  env: Environment;
}

/**
 * Parcel plugin options
 */
interface PluginOptions {
  /** Hot Module Replacement configuration */
  hmrOptions?: HMROptions;
  /** Additional Parcel build options */
  [key: string]: any;
}

/**
 * Result returned by transformer
 */
interface TransformerResult {
  /** Asset type */
  type: string;
  /** Asset content */
  content?: string | Buffer;
  /** Unique identifier for the asset */
  uniqueKey?: string;
  /** Bundle behavior */
  bundleBehavior?: BundleBehavior;
  /** Environment configuration */
  env?: Environment;
  /** Additional metadata */
  meta?: Record<string, any>;
}

Dependency and Asset Conversion

/**
 * Utility functions for converting between Rust and JavaScript representations
 * These are used internally by the transformer
 */

/**
 * Convert Rust dependency to Parcel dependency options
 */
function dependencyFromRust(dep: RustDependency): DependencyOptions;

/**
 * Convert Rust asset to Parcel transformer result
 */
function assetFromRust(asset: RustAsset): TransformerResult;

/**
 * Convert Parcel environment to Rust-compatible format
 */
function envToRust(env: Environment): RustEnvironment;

interface DependencyOptions {
  /** Module specifier (file path, npm package, etc.) */
  specifier: string;
  /** Type of specifier (url, esm, commonjs, etc.) */
  specifierType: string;
  /** Dependency priority */
  priority: string;
  /** Bundle behavior for the dependency */
  bundleBehavior?: BundleBehavior;
  /** Whether dependency is optional */
  isOptional: boolean;
  /** Whether dependency needs stable naming */
  needsStableName: boolean;
  /** Environment for the dependency */
  env: Environment;
  /** Source location in HTML */
  loc?: SourceLocation;
  /** Additional metadata */
  meta?: Record<string, any>;
}

interface Environment {
  /** Build context (browser, node, etc.) */
  context: string;
  /** Output format for the build */
  outputFormat: string;
  /** Source type (module, script) */
  sourceType: string;
  /** Whether this is a library build */
  isLibrary: boolean;
  /** Whether to optimize the build */
  shouldOptimize: boolean;
  /** Whether to enable scope hoisting */
  shouldScopeHoist: boolean;
  /** Target engines */
  engines: Record<string, string>;
  /** Whether to include node_modules */
  includeNodeModules: boolean | string[];
}

interface RustEnvironment {
  /** Build context */
  context: string;
  /** Output format */
  outputFormat: string;
  /** Source type */
  sourceType: string;
  /** Environment flags */
  flags: number;
  /** Source map info */
  sourceMap: any;
  /** Location info */
  loc: any;
  /** Include node modules setting */
  includeNodeModules: boolean | string[];
  /** Target engines */
  engines: Record<string, string>;
}

interface RustDependency {
  /** Module specifier */
  specifier: string;
  /** Specifier type */
  specifierType: string;
  /** Dependency priority */
  priority: string;
  /** Bundle behavior */
  bundleBehavior: string;
  /** Dependency flags */
  flags: number;
  /** Environment */
  env: RustEnvironment;
  /** Source location */
  loc?: SourceLocation;
  /** Placeholder information */
  placeholder?: string;
  /** Resolve from path */
  resolveFrom?: string;
  /** Range information */
  range?: SourceRange;
}

interface RustAsset {
  /** Asset type */
  type: string;
  /** Asset content */
  content: string;
  /** Unique key */
  uniqueKey?: string;
  /** Bundle behavior */
  bundleBehavior: string;
  /** Asset flags */
  flags: number;
  /** Environment */
  env: RustEnvironment;
  /** Source location */
  loc?: SourceLocation;
}

interface SourceLocation {
  /** File path */
  filePath: string;
  /** Start position */
  start: SourcePosition;
  /** End position */
  end: SourcePosition;
}

interface SourcePosition {
  /** Line number */
  line: number;
  /** Column number */
  column: number;
}

interface SourceRange {
  /** Start position */
  start: SourcePosition;
  /** End position */
  end: SourcePosition;
}

interface HMROptions {
  /** HMR port */
  port?: number;
  /** HMR host */
  host?: string;
  /** Additional HMR options */
  [key: string]: any;
}

Integration with Parcel

This transformer integrates seamlessly with Parcel's plugin architecture:

  1. Automatic Registration: Automatically used by Parcel for HTML files
  2. Asset Pipeline: Integrates with Parcel's asset transformation pipeline
  3. Dependency Graph: Discovered dependencies are added to Parcel's dependency graph
  4. Bundle Generation: HTML assets use isolated bundle behavior
  5. HMR Support: Supports Hot Module Replacement when enabled
  6. Error Reporting: Uses Parcel's diagnostic system for error reporting

The transformer requires no manual configuration and works out-of-the-box with standard Parcel installations.