@tomjs/vite-plugin-html

English | 中文

A Vite plugin for handling HTML files, providing compression, loading, and CDN functionality.

Install

With pnpm

pnpm add @tomjs/vite-plugin-html -D

With yarn

yarn add @tomjs/vite-plugin-html -D

With npm

npm add @tomjs/vite-plugin-html -D

Usage

Taking Vue/React projects as examples:

Default Plugin

Vue Example

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import html from '@tomjs/vite-plugin-html';

export default defineConfig({
  plugins: [
    vue(),
    html({
      minify: true,
      loading: {
        // selector: '#app',
        after: `<div style="color:#888">loading...</div>`,
      },
      cdn: {
        modules: ['vue', 'vue-router', 'pinia', 'ant-design-vue'],
      },
    }),
  ],
});

React Example

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import html from '@tomjs/vite-plugin-html';

export default defineConfig({
  plugins: [
    react(),
    html({
      minify: true,
      loading: {
        selector: '#root',
        after: `<div style="color:#888">loading...</div>`,
      },
      cdn: {
        modules: ['react', 'react-dom', 'react-router-dom', 'antd'],
      },
    }),
  ],
});

Documentation

index.d.ts provided by unpkg.com.

Parameters

Parameter	Type	Default	Description
minify	`boolean` \| HtmlMinifyOptions	true	Configuration for compression plugin
loading	`boolean` \| HtmlLoadingOptions	false	Configuration for loading plugin
cdn	`false` \| HtmlCdnOptions	false	Configuration for CDN plugin

Using Compression

Compresses HTML code.

Vue Example

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { useHtmlMinifyPlugin } from '@tomjs/vite-plugin-html';

export default defineConfig({
  plugins: [vue(), useHtmlMinifyPlugin()],
});

React Example

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import { useHtmlMinifyPlugin } from '@tomjs/vite-plugin-html';

export default defineConfig({
  plugins: [react(), useHtmlMinifyPlugin()],
});

Parameters

boolean or HtmlMinifyOptions, default is true .

HtmlMinifyOptions

Same as the Options parameter of html-minifier-terser. When the plugin parameter is boolean , the default configuration is as follows. Otherwise, it uses the default configuration of html-minifier-terser .

Parameter	Type	Default	Description
collapseWhitespace	`boolean`	true	Collapse white space that contributes to text nodes
keepClosingSlash	`boolean`	true	Keep the trailing slash on singleton elements
removeComments	`boolean`	true	Remove HTML comments
removeRedundantAttributes	`boolean`	true	Remove attributes when value matches default
removeScriptTypeAttributes	`boolean`	true	Remove `type="text/javascript"` from script tags
removeStyleLinkTypeAttributes	`boolean`	true	Remove `type="text/css"` from style and link tags
useShortDoctype	`boolean`	true	Replace `doctype` with short (HTML5) doctype
minifyCSS	`boolean`	true	Minify CSS in style elements and style attributes (using clean-css)

Using Loading

Adds loading code to the root node of the application to prevent white screens caused by network issues.

Vue Example

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { useHtmlLoadingPlugin } from '@tomjs/vite-plugin-html';

export default defineConfig({
  plugins: [
    vue(),
    useHtmlLoadingPlugin({
      // selector: '#app',
      after: `<div style="color:#888">loading...</div>`,
    }),
  ],
});

React Example

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import { useHtmlLoadingPlugin } from '@tomjs/vite-plugin-html';

export default defineConfig({
  plugins: [
    react(),
    useHtmlLoadingPlugin({
      selector: '#root',
      after: `<div style="color:#888">loading...</div>`,
    }),
  ],
});

Parameters

boolean or HtmlLoadingOptions, default is true .

HtmlLoadingOptions

Parameter	Type	Default	Description
selector	`string`	#app	Selector for loading node
style	`string`	undefined	Custom style code
before	`string`	undefined	Code to add before loading
after	`string`	undefined	Code to add after loading

Using CDN

Changes module configuration to use CDN for vite build , improving build speed and reducing bundle size.

Vue Example

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { useHtmlCdnPlugin } from '@tomjs/vite-plugin-html';

export default defineConfig({
  plugins: [
    vue(),
    useHtmlCdnPlugin({
      modules: ['vue', 'vue-router', 'pinia', 'ant-design-vue'],
    }),
  ],
});

React Example

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import { useHtmlCdnPlugin } from '@tomjs/vite-plugin-html';

export default defineConfig({
  plugins: [
    react(),
    useHtmlCdnPlugin({
      modules: ['react', 'react-dom', 'react-router-dom', 'antd'],
    }),
  ],
});

Parameters

HtmlCdnOptions

Parameter	Type	Default	Description
modules	(NpmModule \| PresetNpmModule \| HtmlInjectCode)[]	[]	Modules to import
type	`'npmmirror' \| 'unpkg' \| 'jsdelivr' \| 'custom'`	'jsdelivr'	`CDN` source type, parameters `name`/`version`/`file` are taken from the modules configuration. When the OS language is `zh_CN` , the default value is `npmmirror`, otherwise it is `jsdelivr`.
url	`string`	''	Custom URL (used with `type` )
local	'boolean' \| 'string[]' \| HtmlCdnLocal	false	Local mode or specific modules

CDN type:

npmmirror: url defaults to https://registry.npmmirror.com/{name}/{version}/files/{file}
jsdelivr: url defaults to https://cdn.jsdelivr.net/npm/{name}@{version}/{file}
unpkg: url defaults to https://unpkg.com/{name}@{version}/{file}
custom: custom url can be defined

NpmModule

Configuration for CDN modules.

Parameter	Type	Default	Description
name	`string`	undefined	Name of the package
var	`string`	undefined	Global variable name (defaults to PascalCase name)
version	`string`	undefined	Package version (defaults to version in node_modules)
file	`string \| string[]`	undefined	Path to the resource JS/CSS file
modulePath	`string`	undefined	Set npm module path
deps	`string[]`	undefined	Dependent modules
local	`boolean`	false	Whether it is a local module
injectBefore	`string \| string[]`	undefined	These codes will be inserted before the script/link tag of the current module.The `{url}` keyword in the code will be replaced with relevant information about the current module.
injectAfter	`string \| string[]`	undefined	These codes will be inserted after the script/link tag of the current module.The `{url}` keyword in the code will be replaced with relevant information about the current module.

Example:

const modules = [
  {
    name: 'lodash',
    var: '_',
    file: 'lodash.min.js',
  },
  {
    name: 'vue',
    var: 'Vue',
  },
  {
    name: 'vue-router',
    deps: ['vue'],
  },
  {
    name: 'ant-design-vue',
    deps: ['vue', 'vue-router'],
    file: ['dist/antd.min.js'],
  },
];

PresetNpmModule

Default supported types, internally mapped to corresponding NpmModule configurations:

dayjs
axios
lodash
vue
vue-router
vue-demi
pinia
ant-design-vue
ant-design-vue3
@vueuse/core
@vueuse/shared
element-plus
react
react-dom
react-router-dom
antd
ahooks
@ant-design/charts

WARNING

Some modules are introduced using CDN, and other dependencies must be introduced first. When using package management tools such as pnpm, if the module's dependencies are not explicitly installed, the module's dependency information may not be obtained in node_modules, and the following exceptions may occur:

The URL of CDN has no version number
In local mode, dependencies are thrown in the form of CDN URL

You can try to proactively install related dependencies to solve them. The following are some module dependencies:

antd
- dayjs
ant-design-vue
- dayjs
pinia
- vue-demi
@vueuse/core
- @vueuse/shared

Currently, this library uses pnpm list to read dependencies to solve this problem. If you encounter this problem with other npm tools, please contact the author to add relevant support. Thanks.

HtmlInjectCode

Injected HTML page code.

Parameter	Type	Default	Description
code	`string`	undefined	HTML page code to inject

HtmlCdnLocal

Local configuration for CDN.

Parameter	Type	Default	Description
modules	`'boolean' \| string[]`	false	Local mode or specific modules
base	'string'	'/'	Same as Vite's `base` option
outDir	'string'	'dist'	Local output directory, defaults to Vite's `build.outDir`
path	'string'	'npm/{name}@{version}'	Local output path, module URLs will also be replaced with this path
copy	'boolean'	true	Whether to copy to local directory

Development

Development requirements:
- git
- node>=18
- pnpm>=8
For first-time use, install dependencies by running the following commands:

# Install dependencies
pnpm i
# build library
pnpm build

To debug the vue project, execute the following commands:

cd examples/vue
pnpm build
pnpm preview

To debug the react project, execute the following commands:

cd examples/react
pnpm build
pnpm preview

tomjs/vite-plugin-html

@tomjs/vite-plugin-html

Install

Usage

Default Plugin

Vue Example

React Example

Documentation

Parameters

Using Compression

Vue Example

React Example

Parameters

HtmlMinifyOptions

Using Loading

Vue Example

React Example

Parameters

HtmlLoadingOptions

Using CDN

Vue Example

React Example

Parameters

HtmlCdnOptions

NpmModule

PresetNpmModule

HtmlInjectCode

HtmlCdnLocal

Development

References