0
# Vite Plugin HTML
1

2
Vite Plugin HTML is a comprehensive Vite plugin that enhances HTML processing capabilities for modern web development workflows. It provides HTML compression using html-minifier-terser, EJS template processing with lodash.template syntax support, and multi-page application support for complex project configurations.
3

4
## Package Information
5

6
- **Package Name**: vite-plugin-html
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install vite-plugin-html -D`
10
- **Peer Dependencies**: Vite >=2.0.0
11

12
## Core Imports
13

14
```typescript
15
import { createHtmlPlugin } from "vite-plugin-html";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { createHtmlPlugin } = require("vite-plugin-html");
22
```
23

24
## Basic Usage
25

26
### Single Page Application (SPA)
27

28
```typescript
29
import { defineConfig } from 'vite';
30
import { createHtmlPlugin } from 'vite-plugin-html';
31

32
export default defineConfig({
33
  plugins: [
34
    createHtmlPlugin({
35
      minify: true,
36
      entry: 'src/main.ts',
37
      template: 'public/index.html',
38
      inject: {
39
        data: {
40
          title: 'My App',
41
          injectScript: `<script src="./analytics.js"></script>`,
42
        },
43
        tags: [
44
          {
45
            injectTo: 'body-prepend',
46
            tag: 'div',
47
            attrs: {
48
              id: 'root',
49
            },
50
          },
51
        ],
52
      },
53
    }),
54
  ],
55
});
56
```
57

58
### Multi-Page Application (MPA)
59

60
```typescript
61
import { defineConfig } from 'vite';
62
import { createHtmlPlugin } from 'vite-plugin-html';
63

64
export default defineConfig({
65
  plugins: [
66
    createHtmlPlugin({
67
      minify: true,
68
      pages: [
69
        {
70
          entry: 'src/main.ts',
71
          filename: 'index.html',
72
          template: 'public/index.html',
73
          injectOptions: {
74
            data: {
75
              title: 'Home Page',
76
            },
77
          },
78
        },
79
        {
80
          entry: 'src/admin.ts',
81
          filename: 'admin.html',
82
          template: 'public/admin.html',
83
          injectOptions: {
84
            data: {
85
              title: 'Admin Panel',
86
            },
87
          },
88
        },
89
      ],
90
    }),
91
  ],
92
});
93
```
94

95
## Capabilities
96

97
### Plugin Creation
98

99
Creates the main Vite plugin for HTML processing and minification.
100

101
```typescript { .api }
102
function createHtmlPlugin(userOptions?: UserOptions): PluginOption[];
103
```
104

105
**Parameters:**
106
- `userOptions?: UserOptions` - Configuration options for the plugin
107

108
**Returns:**
109
- `PluginOption[]` - Array containing the HTML processing plugin and minification plugin
110

111
## Configuration Types
112

113
### UserOptions
114

115
Main configuration interface for the plugin.
116

117
```typescript { .api }
118
interface UserOptions {
119
  /** Multi-page application configuration */
120
  pages?: Pages;
121
  /** HTML minification settings - boolean or detailed options */
122
  minify?: MinifyOptions | boolean;
123
  /** Default entry script path */
124
  entry?: string;
125
  /** Default template file path */
126
  template?: string;
127
  /** Default injection options */
128
  inject?: InjectOptions;
129
  /** Enable warning logs (default: false) */
130
  verbose?: boolean;
131
}
132
```
133

134
### InjectOptions
135

136
Configuration for HTML content injection including EJS template data and HTML tags.
137

138
```typescript { .api }
139
interface InjectOptions {
140
  /** Data injected into the HTML template using EJS */
141
  data?: Record<string, any>;
142
  /** HTML tags to inject at specified locations */
143
  tags?: HtmlTagDescriptor[];
144
  /** EJS template engine configuration options */
145
  ejsOptions?: EJSOptions;
146
}
147
```
148

149
### PageOption
150

151
Configuration for individual pages in multi-page applications.
152

153
```typescript { .api }
154
interface PageOption {
155
  /** Output HTML filename */
156
  filename: string;
157
  /** Template file path */
158
  template: string;
159
  /** Entry script path for this page */
160
  entry?: string;
161
  /** Injection options specific to this page */
162
  injectOptions?: InjectOptions;
163
}
164
```
165

166
### Supporting Types
167

168
```typescript { .api }
169
type Entry = string | Record<string, string>;
170
type Pages = PageOption[];
171
```
172

173
**Re-exported Types:**
174
- `EJSOptions` - from 'ejs' package for template configuration
175
- `MinifyOptions` - from 'html-minifier-terser' package for compression settings
176
- `HtmlTagDescriptor` - from 'vite' package for HTML tag injection
177

178
## Features
179

180
### EJS Template Processing
181

182
The plugin processes HTML templates using EJS syntax with automatic environment variable injection:
183

184
```html
185
<!-- index.html -->
186
<!DOCTYPE html>
187
<html>
188
<head>
189
  <title><%- title %></title>
190
  <%- injectScript %>
191
</head>
192
<body>
193
  <div id="app"></div>
194
</body>
195
</html>
196
```
197

198
### Environment Variable Injection
199

200
Environment variables from `.env` files are automatically injected into templates:
201

202
- `.env.${mode}.local`
203
- `.env.${mode}`
204
- `.env.local`
205
- `.env`
206

207
### HTML Minification
208

209
Default minification settings when `minify: true`:
210

211
```typescript { .api }
212
interface DefaultMinifyOptions {
213
  collapseWhitespace: true;
214
  keepClosingSlash: true;
215
  removeComments: true;
216
  removeRedundantAttributes: true;
217
  removeScriptTypeAttributes: true;
218
  removeStyleLinkTypeAttributes: true;
219
  useShortDoctype: true;
220
  minifyCSS: true;
221
}
222
```
223

224
### Development Server Integration
225

226
The plugin integrates with Vite's development server to provide:
227

228
- History API fallback for SPA routing
229
- Multi-page route handling
230
- Template processing during development
231
- Hot module replacement support
232

233
### Build Integration
234

235
During build, the plugin:
236

237
- Processes HTML templates with injected data
238
- Minifies HTML output (when enabled)
239
- Handles multi-page build configurations
240
- Manages entry point injection and cleanup
241
- Organizes output files in the build directory
242

243
## Error Handling
244

245
The plugin provides clear error messages for common issues:
246

247
- Missing template files: throws descriptive error with file path
248
- Invalid EJS syntax: passes through EJS error messages
249
- Configuration conflicts: logs warnings when verbose mode is enabled
250

251
## Platform Support
252

253
- **Node.js**: >=12.0.0
254
- **Vite**: >=2.0.0 (peer dependency)
255
- **Browsers**: Supports all modern browsers through Vite's build process
256
- **Build Tools**: Integrates with Vite's build pipeline and dev server