Skip to content

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

License

Notifications You must be signed in to change notification settings

tomjs/vite-plugin-html

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

78 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@tomjs/vite-plugin-html

npm node-current (scoped) NPM Docs

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

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:

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

References