tessl/npm-rollup--plugin-html
Creates HTML files to serve Rollup bundles with extensive customization options for build workflows
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-rollup--plugin-html@2.0.00
# @rollup/plugin-html
1
2
@rollup/plugin-html is a Rollup plugin that automatically creates HTML files to serve Rollup bundles. It provides extensive customization options including configurable HTML templates, meta tag injection, script and link attribute customization, and support for multiple output formats (ESM, IIFE, UMD). The plugin handles automatic script and stylesheet inclusion based on bundle outputs, supports custom public paths for asset deployment, and provides utility functions for HTML attribute generation.
3
4
## Package Information
5
6
- **Package Name**: @rollup/plugin-html
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @rollup/plugin-html --save-dev`
10
- **Requirements**: Node.js v14.0.0+, Rollup v1.20.0+
11
12
## Core Imports
13
14
```typescript
15
import html from "@rollup/plugin-html";
16
import { makeHtmlAttributes } from "@rollup/plugin-html";
17
```
18
19
For CommonJS:
20
21
```javascript
22
const html = require("@rollup/plugin-html");
23
const { makeHtmlAttributes } = require("@rollup/plugin-html");
24
```
25
26
## Basic Usage
27
28
```typescript
29
import html from "@rollup/plugin-html";
30
31
// Basic plugin usage with default settings
32
export default {
33
input: "src/index.js",
34
output: {
35
dir: "dist",
36
format: "es"
37
},
38
plugins: [html()]
39
};
40
41
// Custom configuration
42
export default {
43
input: "src/index.js",
44
output: {
45
dir: "dist",
46
format: "iife"
47
},
48
plugins: [
49
html({
50
title: "My Application",
51
fileName: "app.html",
52
publicPath: "/assets/",
53
meta: [
54
{ charset: "utf-8" },
55
{ name: "viewport", content: "width=device-width, initial-scale=1" }
56
]
57
})
58
]
59
};
60
```
61
62
## Architecture
63
64
@rollup/plugin-html integrates into Rollup's build pipeline through the `generateBundle` hook:
65
66
- **Plugin Integration**: Registers as a Rollup plugin and processes bundles during the generate phase
67
- **Bundle Analysis**: Automatically detects CSS and JavaScript files from the bundle output
68
- **Template System**: Uses a default HTML template or accepts custom template functions for complete control
69
- **Format Detection**: Automatically handles ES module type attributes and warns about unsupported formats
70
- **Asset Management**: Organizes bundle files by extension and applies appropriate HTML elements
71
72
## Capabilities
73
74
### HTML Plugin Function
75
76
Creates a Rollup plugin that generates HTML files to serve bundles.
77
78
```typescript { .api }
79
/**
80
* A Rollup plugin which creates HTML files to serve Rollup bundles.
81
* @param options - Plugin configuration options
82
* @returns Plugin instance for Rollup
83
*/
84
function html(options?: RollupHtmlOptions): Plugin;
85
86
interface RollupHtmlOptions {
87
/** Place scripts in the <head> tag instead of <body> */
88
addScriptsToHead?: boolean;
89
/** HTML attributes for html, link, and script elements */
90
attributes?: Record<string, any>;
91
/** Name of the HTML file to generate */
92
fileName?: string;
93
/** Meta tag attributes */
94
meta?: Record<string, any>[];
95
/** Path to prepend to bundle assets */
96
publicPath?: string;
97
/** Custom template function for HTML generation */
98
template?: (templateOptions: RollupHtmlTemplateOptions) => string | Promise<string>;
99
/** HTML document title */
100
title?: string;
101
}
102
```
103
104
**Usage Examples:**
105
106
```typescript
107
// Minimal usage with defaults
108
html()
109
110
// Comprehensive configuration
111
html({
112
title: "My Web App",
113
fileName: "index.html",
114
publicPath: "https://cdn.example.com/",
115
addScriptsToHead: false,
116
attributes: {
117
html: { lang: "en", "data-theme": "dark" },
118
script: { defer: true },
119
link: { crossorigin: "anonymous" }
120
},
121
meta: [
122
{ charset: "utf-8" },
123
{ name: "description", content: "My awesome web application" },
124
{ name: "viewport", content: "width=device-width, initial-scale=1" }
125
]
126
})
127
128
// Custom template function
129
html({
130
template: ({ attributes, files, meta, publicPath, title }) => {
131
const scripts = (files.js || [])
132
.filter(file => file.type === 'chunk' && file.isEntry)
133
.map(file => `<script src="${publicPath}${file.fileName}"></script>`)
134
.join('\n');
135
136
const styles = (files.css || [])
137
.map(file => `<link href="${publicPath}${file.fileName}" rel="stylesheet">`)
138
.join('\n');
139
140
return `<!DOCTYPE html>
141
<html>
142
<head>
143
<title>${title}</title>
144
${styles}
145
</head>
146
<body>
147
<div id="app"></div>
148
${scripts}
149
</body>
150
</html>`;
151
}
152
})
153
```
154
155
### HTML Attributes Utility
156
157
Converts an object of attributes to a space-separated HTML attribute string.
158
159
```typescript { .api }
160
/**
161
* Consumes an object with key-value pairs that represent HTML element attribute names and values.
162
* Returns all pairs as a space-separated string of valid HTML element attributes.
163
* @param attributes - Object with attribute name-value pairs
164
* @returns Space-separated string of HTML attributes
165
*/
166
function makeHtmlAttributes(attributes: Record<string, any>): string;
167
```
168
169
**Usage Examples:**
170
171
```typescript
172
import { makeHtmlAttributes } from "@rollup/plugin-html";
173
174
// Basic attributes
175
makeHtmlAttributes({ lang: "en", class: "app" });
176
// Returns: ' lang="en" class="app"'
177
178
// Data attributes
179
makeHtmlAttributes({
180
"data-theme": "dark",
181
"data-version": "1.0.0",
182
id: "main"
183
});
184
// Returns: ' data-theme="dark" data-version="1.0.0" id="main"'
185
186
// Boolean attributes
187
makeHtmlAttributes({ defer: true, async: false });
188
// Returns: ' defer="true" async="false"'
189
190
// Empty or null attributes object
191
makeHtmlAttributes({});
192
// Returns: ''
193
194
makeHtmlAttributes(null);
195
// Returns: ''
196
```
197
198
### Template Options Interface
199
200
Parameters passed to custom template functions.
201
202
```typescript { .api }
203
interface RollupHtmlTemplateOptions {
204
/** Scripts placement configuration */
205
addScriptsToHead?: boolean;
206
/** Element attributes configuration */
207
attributes: Record<string, any>;
208
/** Complete Rollup output bundle */
209
bundle: OutputBundle;
210
/** Bundle files organized by extension (js, css, etc.) */
211
files: Record<string, (OutputChunk | OutputAsset)[]>;
212
/** Meta tag configuration array */
213
meta: Record<string, any>[];
214
/** Asset path prefix */
215
publicPath: string;
216
/** HTML document title */
217
title: string;
218
}
219
```
220
221
## Configuration Details
222
223
### Supported Output Formats
224
225
- **Fully Supported**: `es`/`esm`, `iife`, `umd` - These formats work out of the box with the default template
226
- **Partially Supported**: `amd`, `system`, `cjs` - These formats require custom templates and may need additional loaders
227
- **ES Module Handling**: When using `es` or `esm` format, `type="module"` is automatically added to script attributes
228
229
### Default Configuration
230
231
```typescript
232
const defaults = {
233
attributes: {
234
link: null,
235
html: { lang: "en" },
236
script: null
237
},
238
fileName: "index.html",
239
meta: [{ charset: "utf-8" }],
240
publicPath: "",
241
template: defaultTemplate, // Internal default template
242
title: "Rollup Bundle",
243
addScriptsToHead: false
244
};
245
```
246
247
### File Organization
248
249
The plugin automatically organizes bundle files by extension:
250
251
- **JavaScript files** (`files.js`): Script tags are created for entry chunks only
252
- **CSS files** (`files.css`): Link tags are created for all CSS assets
253
- **Other assets**: Available in the files object but not automatically included in default template
254
255
### Error Handling
256
257
- **Unsupported Formats**: Plugin warns when using unsupported output formats without a custom template
258
- **Missing Assets**: Gracefully handles bundles without CSS or JavaScript files
259
- **Template Errors**: Template function errors are propagated to Rollup's error handling
260
261
## Types
262
263
```typescript { .api }
264
// From Rollup core - used in plugin interfaces
265
interface Plugin {
266
name: string;
267
generateBundle?(
268
options: NormalizedOutputOptions,
269
bundle: OutputBundle
270
): void | Promise<void>;
271
}
272
273
interface OutputBundle {
274
[fileName: string]: OutputAsset | OutputChunk;
275
}
276
277
interface OutputChunk {
278
type: 'chunk';
279
fileName: string;
280
isEntry: boolean;
281
// ... other Rollup chunk properties
282
}
283
284
interface OutputAsset {
285
type: 'asset';
286
fileName: string;
287
source: string | Uint8Array;
288
// ... other Rollup asset properties
289
}
290
291
interface NormalizedOutputOptions {
292
format: string;
293
// ... other Rollup output options
294
}
295
```