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
To install, run
npx @tessl/cli install tessl/npm-parcel--transformer-html@2.15.00
# Parcel HTML Transformer
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: @parcel/transformer-html
7
- **Package Type**: npm
8
- **Language**: JavaScript (Flow-typed)
9
- **Installation**: Automatically installed as part of Parcel 2.x
10
- **Parcel Version**: 2.15.3+
11
12
## Core Imports
13
14
This package is designed to be used as a Parcel plugin and is not typically imported directly. However, if needed:
15
16
```javascript
17
const HTMLTransformer = require("@parcel/transformer-html");
18
```
19
20
For ES modules:
21
22
```javascript
23
import HTMLTransformer from "@parcel/transformer-html";
24
```
25
26
## Basic Usage
27
28
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:
29
30
```html
31
<!-- index.html -->
32
<!DOCTYPE html>
33
<html>
34
<head>
35
<title>My App</title>
36
<link rel="stylesheet" href="./styles.css">
37
</head>
38
<body>
39
<div id="app"></div>
40
<script src="./main.js"></script>
41
</body>
42
</html>
43
```
44
45
The transformer will automatically:
46
- Process the HTML content through Rust-based parsing
47
- Extract dependencies (CSS files, JavaScript modules, images, etc.)
48
- Handle asset transformation and bundling
49
- Support Hot Module Replacement (HMR) when enabled
50
51
## Capabilities
52
53
### HTML File Processing
54
55
Processes HTML files through Parcel's transformation pipeline with automatic dependency extraction and asset handling.
56
57
```javascript { .api }
58
/**
59
* Default export: Configured Transformer instance for HTML processing
60
* This is the main export used by Parcel's plugin system
61
*/
62
export default Transformer;
63
64
/**
65
* Transformer configuration object
66
*/
67
interface TransformerConfig {
68
transform(context: TransformContext): Promise<Array<TransformerResult>>;
69
}
70
71
interface TransformContext {
72
/** The HTML asset being transformed */
73
asset: MutableAsset;
74
/** Parcel build options including HMR settings */
75
options: PluginOptions;
76
}
77
```
78
79
### File Type Support
80
81
The transformer handles multiple HTML-related file types with appropriate processing.
82
83
```javascript { .api }
84
/**
85
* Supported file extensions:
86
* - .html: Standard HTML files
87
* - .htm: Converted to .html type during processing
88
* - .xhtml: Processed with XML parsing mode enabled
89
*/
90
type SupportedExtensions = '.html' | '.htm' | '.xhtml';
91
```
92
93
### Asset Processing Behavior
94
95
All HTML assets processed by this transformer receive specific bundle configuration.
96
97
```javascript { .api }
98
/**
99
* Bundle behavior applied to HTML assets
100
* 'isolated' ensures HTML files are processed in separate bundles
101
*/
102
type BundleBehavior = 'isolated';
103
```
104
105
### Transformation Process
106
107
The core transformation leverages Rust-based HTML parsing for performance and accuracy.
108
109
```javascript { .api }
110
/**
111
* Rust-based HTML transformation function (from @parcel/rust)
112
* Called internally by the transformer
113
*/
114
function transformHtml(options: HtmlTransformOptions): HtmlTransformResult;
115
116
interface HtmlTransformOptions {
117
/** HTML content as Buffer */
118
code: Buffer;
119
/** Path to the HTML file */
120
filePath: string;
121
/** Enable XML parsing for .xhtml files */
122
xml: boolean;
123
/** Parcel environment configuration converted to Rust format */
124
env: RustEnvironment;
125
/** Enable HMR support */
126
hmr: boolean;
127
}
128
129
interface HtmlTransformResult {
130
/** Transformed HTML code */
131
code: Buffer;
132
/** Extracted dependencies (CSS, JS, images, etc.) */
133
dependencies: RustDependency[];
134
/** Additional assets generated during transformation */
135
assets: RustAsset[];
136
/** Any errors encountered during transformation */
137
errors: Array<Diagnostic>;
138
}
139
```
140
141
### Error Handling
142
143
The transformer provides comprehensive error handling with detailed diagnostics.
144
145
```javascript { .api }
146
/**
147
* Error thrown when HTML transformation fails
148
* Uses Parcel's diagnostic system for detailed error reporting
149
*/
150
class ThrowableDiagnostic extends Error {
151
constructor(options: { diagnostic: Array<Diagnostic> });
152
}
153
154
interface Diagnostic {
155
/** Error message */
156
message: string;
157
/** File location information */
158
location?: SourceLocation;
159
/** Additional error context */
160
hints?: string[];
161
}
162
```
163
164
## Types
165
166
### Core Transformation Types
167
168
```javascript { .api }
169
/**
170
* Parcel Asset interface for HTML files
171
*/
172
interface MutableAsset {
173
/** Asset type (.html, .htm, .xhtml) */
174
type: string;
175
/** File path of the asset */
176
filePath: string;
177
/** Asset content as Buffer */
178
getBuffer(): Promise<Buffer>;
179
/** Set transformed content */
180
setBuffer(content: Buffer): void;
181
/** Add dependency discovered during transformation */
182
addDependency(dependency: DependencyOptions): void;
183
/** Bundle behavior setting */
184
bundleBehavior: BundleBehavior;
185
/** Environment configuration */
186
env: Environment;
187
}
188
189
/**
190
* Parcel plugin options
191
*/
192
interface PluginOptions {
193
/** Hot Module Replacement configuration */
194
hmrOptions?: HMROptions;
195
/** Additional Parcel build options */
196
[key: string]: any;
197
}
198
199
/**
200
* Result returned by transformer
201
*/
202
interface TransformerResult {
203
/** Asset type */
204
type: string;
205
/** Asset content */
206
content?: string | Buffer;
207
/** Unique identifier for the asset */
208
uniqueKey?: string;
209
/** Bundle behavior */
210
bundleBehavior?: BundleBehavior;
211
/** Environment configuration */
212
env?: Environment;
213
/** Additional metadata */
214
meta?: Record<string, any>;
215
}
216
```
217
218
### Dependency and Asset Conversion
219
220
```javascript { .api }
221
/**
222
* Utility functions for converting between Rust and JavaScript representations
223
* These are used internally by the transformer
224
*/
225
226
/**
227
* Convert Rust dependency to Parcel dependency options
228
*/
229
function dependencyFromRust(dep: RustDependency): DependencyOptions;
230
231
/**
232
* Convert Rust asset to Parcel transformer result
233
*/
234
function assetFromRust(asset: RustAsset): TransformerResult;
235
236
/**
237
* Convert Parcel environment to Rust-compatible format
238
*/
239
function envToRust(env: Environment): RustEnvironment;
240
241
interface DependencyOptions {
242
/** Module specifier (file path, npm package, etc.) */
243
specifier: string;
244
/** Type of specifier (url, esm, commonjs, etc.) */
245
specifierType: string;
246
/** Dependency priority */
247
priority: string;
248
/** Bundle behavior for the dependency */
249
bundleBehavior?: BundleBehavior;
250
/** Whether dependency is optional */
251
isOptional: boolean;
252
/** Whether dependency needs stable naming */
253
needsStableName: boolean;
254
/** Environment for the dependency */
255
env: Environment;
256
/** Source location in HTML */
257
loc?: SourceLocation;
258
/** Additional metadata */
259
meta?: Record<string, any>;
260
}
261
262
interface Environment {
263
/** Build context (browser, node, etc.) */
264
context: string;
265
/** Output format for the build */
266
outputFormat: string;
267
/** Source type (module, script) */
268
sourceType: string;
269
/** Whether this is a library build */
270
isLibrary: boolean;
271
/** Whether to optimize the build */
272
shouldOptimize: boolean;
273
/** Whether to enable scope hoisting */
274
shouldScopeHoist: boolean;
275
/** Target engines */
276
engines: Record<string, string>;
277
/** Whether to include node_modules */
278
includeNodeModules: boolean | string[];
279
}
280
281
interface RustEnvironment {
282
/** Build context */
283
context: string;
284
/** Output format */
285
outputFormat: string;
286
/** Source type */
287
sourceType: string;
288
/** Environment flags */
289
flags: number;
290
/** Source map info */
291
sourceMap: any;
292
/** Location info */
293
loc: any;
294
/** Include node modules setting */
295
includeNodeModules: boolean | string[];
296
/** Target engines */
297
engines: Record<string, string>;
298
}
299
300
interface RustDependency {
301
/** Module specifier */
302
specifier: string;
303
/** Specifier type */
304
specifierType: string;
305
/** Dependency priority */
306
priority: string;
307
/** Bundle behavior */
308
bundleBehavior: string;
309
/** Dependency flags */
310
flags: number;
311
/** Environment */
312
env: RustEnvironment;
313
/** Source location */
314
loc?: SourceLocation;
315
/** Placeholder information */
316
placeholder?: string;
317
/** Resolve from path */
318
resolveFrom?: string;
319
/** Range information */
320
range?: SourceRange;
321
}
322
323
interface RustAsset {
324
/** Asset type */
325
type: string;
326
/** Asset content */
327
content: string;
328
/** Unique key */
329
uniqueKey?: string;
330
/** Bundle behavior */
331
bundleBehavior: string;
332
/** Asset flags */
333
flags: number;
334
/** Environment */
335
env: RustEnvironment;
336
/** Source location */
337
loc?: SourceLocation;
338
}
339
340
interface SourceLocation {
341
/** File path */
342
filePath: string;
343
/** Start position */
344
start: SourcePosition;
345
/** End position */
346
end: SourcePosition;
347
}
348
349
interface SourcePosition {
350
/** Line number */
351
line: number;
352
/** Column number */
353
column: number;
354
}
355
356
interface SourceRange {
357
/** Start position */
358
start: SourcePosition;
359
/** End position */
360
end: SourcePosition;
361
}
362
363
interface HMROptions {
364
/** HMR port */
365
port?: number;
366
/** HMR host */
367
host?: string;
368
/** Additional HMR options */
369
[key: string]: any;
370
}
371
```
372
373
## Integration with Parcel
374
375
This transformer integrates seamlessly with Parcel's plugin architecture:
376
377
1. **Automatic Registration**: Automatically used by Parcel for HTML files
378
2. **Asset Pipeline**: Integrates with Parcel's asset transformation pipeline
379
3. **Dependency Graph**: Discovered dependencies are added to Parcel's dependency graph
380
4. **Bundle Generation**: HTML assets use isolated bundle behavior
381
5. **HMR Support**: Supports Hot Module Replacement when enabled
382
6. **Error Reporting**: Uses Parcel's diagnostic system for error reporting
383
384
The transformer requires no manual configuration and works out-of-the-box with standard Parcel installations.