0
# HTML Loader
1

2
HTML Loader is a webpack loader that processes HTML files by importing referenced assets, minifying content, and generating JavaScript modules. It automatically handles HTML attributes like `src`, `href`, and `srcset` to integrate images, stylesheets, scripts, and other assets into the webpack build process.
3

4
## Package Information
5

6
- **Package Name**: html-loader
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev html-loader`
10

11
## Core Imports
12

13
The html-loader is configured in webpack and doesn't export functions for direct import. Instead, it provides configuration options and utilities:
14

15
```javascript
16
// Access default minimizer options
17
const { defaultMinimizerOptions } = require("html-loader");
18
```
19

20
For webpack configuration:
21

22
```javascript
23
module.exports = {
24
  module: {
25
    rules: [
26
      {
27
        test: /\.html$/i,
28
        loader: "html-loader",
29
      },
30
    ],
31
  },
32
};
33
```
34

35
## Basic Usage
36

37
```javascript
38
// webpack.config.js
39
module.exports = {
40
  module: {
41
    rules: [
42
      {
43
        test: /\.html$/i,
44
        loader: "html-loader",
45
        options: {
46
          sources: true,
47
          minimize: true,
48
        },
49
      },
50
    ],
51
  },
52
};
53
```
54

55
```html
56
<!-- template.html -->
57
<div>
58
  <img src="./image.png" alt="Example" />
59
  <link rel="stylesheet" href="./styles.css" />
60
</div>
61
```
62

63
```javascript
64
// main.js
65
import html from "./template.html";
66
console.log(html); // HTML string with processed asset URLs
67
```
68

69
## Architecture
70

71
HTML Loader operates through several key components:
72

73
- **Webpack Loader Interface**: Main processing function that handles HTML content transformation
74
- **Sources Plugin**: Configurable HTML attribute processing for asset detection and import generation
75
- **Minimizer Plugin**: HTML minification using html-minifier-terser with customizable options
76
- **Runtime Utilities**: Helper functions for URL processing and code generation
77
- **Options Validation**: Schema-based validation of loader configuration options
78
- **Error Handling**: Custom error reporting with source position information
79

80
## Capabilities
81

82
### HTML Asset Processing
83

84
Automatically processes HTML attributes to import assets through webpack's module system. Supports extensive customization of which elements and attributes to process.
85

86
```javascript { .api }
87
// Webpack loader configuration options
88
interface LoaderOptions {
89
  sources?: boolean | SourcesOptions;
90
  minimize?: boolean | MinimizeOptions;
91
  esModule?: boolean;
92
  preprocessor?: (content: string, loaderContext: LoaderContext) => string | Promise<string>;
93
  postprocessor?: (content: string, loaderContext: LoaderContext) => string | Promise<string>;
94
}
95

96
interface SourcesOptions {
97
  list?: SourceDefinition[];
98
  urlFilter?: (attribute: string, value: string, resourcePath: string) => boolean;
99
  scriptingEnabled?: boolean;
100
}
101

102
interface SourceDefinition {
103
  tag?: string;
104
  attribute?: string;
105
  type: "src" | "srcset";
106
  filter?: (tag: string, attribute: string, attributes: string, resourcePath: string) => boolean;
107
}
108
```
109

110
[Asset Processing](./asset-processing.md)
111

112
### HTML Minification
113

114
Built-in HTML minification with extensive configuration options using html-minifier-terser. Automatically enabled in production mode with sensible defaults.
115

116
```javascript { .api }
117
interface MinimizeOptions {
118
  caseSensitive?: boolean;
119
  collapseWhitespace?: boolean;
120
  conservativeCollapse?: boolean;
121
  keepClosingSlash?: boolean;
122
  minifyCSS?: boolean;
123
  minifyJS?: boolean;
124
  removeComments?: boolean;
125
  removeRedundantAttributes?: boolean;
126
  removeScriptTypeAttributes?: boolean;
127
  removeStyleLinkTypeAttributes?: boolean;
128
}
129

130
// Access default options
131
const defaultMinimizerOptions: MinimizeOptions;
132
```
133

134
[Minification](./minification.md)
135

136
### Content Processing
137

138
Pre and post-processing hooks for custom HTML transformations, enabling integration with template engines and other processing tools.
139

140
```javascript { .api }
141
type PreprocessorFunction = (
142
  content: string,
143
  loaderContext: LoaderContext
144
) => string | Promise<string>;
145

146
type PostprocessorFunction = (
147
  content: string,
148
  loaderContext: LoaderContext
149
) => string | Promise<string>;
150
```
151

152
[Content Processing](./content-processing.md)
153

154
### Runtime Utilities
155

156
Helper functions and utilities used at runtime for URL processing and asset handling.
157

158
```javascript { .api }
159
/**
160
 * Runtime helper for URL processing with optional quote handling
161
 * @param url - The URL to process
162
 * @param maybeNeedQuotes - Whether quotes might be needed for the URL
163
 * @returns Processed URL string, optionally wrapped in quotes
164
 */
165
function getUrl(url: string, maybeNeedQuotes?: boolean): string;
166
```
167

168
[Runtime Utilities](./runtime-utilities.md)
169

170
## Types
171

172
```javascript { .api }
173
interface LoaderContext {
174
  resourcePath: string;
175
  context: string;
176
  mode?: string;
177
  emitError: (error: Error) => void;
178
  getOptions: (schema?: object) => any;
179
}
180

181
class HtmlSourceError extends Error {
182
  constructor(error: string, startOffset: number, endOffset: number, source: string);
183
  name: "HtmlSourceError";
184
  message: string; // Enhanced with position information (line, column)
185
  startOffset: number;
186
  endOffset: number;
187
  source: string;
188
  stack: false; // Stack trace is disabled for cleaner output
189
}
190
```