Awesome

@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

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 .

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

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

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.

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.

HtmlCdnLocal

Local configuration for CDN.

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

• vite-plugin-html
• ant-design-pro
• vite-plugin-cdn-import