Сборщик Vite предоставляет не только хороший функционал, но и удобный API для создания плагинов, позволяющих кастомизировать его практически под любую задачу. То есть, плагины можно писать не только для публикации их в npmjs.com репозитории, но и для автоматизации исключительно своих задач.

Сложность написания плагина сравнима со сложностью написания сценария для Gulp или GitHub Actions. Для примера напишем плагин, который будет вставлять фрагменты кода в файл index.html. В зависимости от проекта в данный файл необходимо помещать код Google Analytics, метатэги Open Graph и Twitter, подключение Service worker-a, виджета чата поддержки, сплэш скрин и многое другое. В результате index.html становится очень большим и ориентироваться в нем и блоках кода довольно сложно.

Наш плагин позволить держать фрагменты кода в отдельных файлах, а при сборке все будет помещаться в index.html. Причем это будет происходить не только при непосредственно сборке ( npm build ), но и при запуске Vite dev сервера с поддержкой HRM (Hot Module Replacement).

Репозиторий плагина - https://github.com/altrusl/vite-plugin-html-injection
NPM - https://www.npmjs.com/package/vite-plugin-html-injection

Система плагинов Vite

Плагины Vite являются расширением плагинов сборщика Rollup, который используется для сборки Vite проекта под капотом. За небольшим исключением плагины Rollup работают в Vite, в то же время последний добавляет несколько хуков в API для плагинов, которые мы и будет использовать.

Написание плагина по большому счету является написанием кода для данных хуков. Мы задействуем два из них.

vite-plugin-html-injection

Первый используемый хук - configResolved. Он нужен для того, чтобы получить конфиг Vite, из которого мы позже получим абсолютный путь к директории проекта - config.root

Второй хук - transformIndexHtml. В нем непосредственно нужно произвести изменение содержимого index.html. Аргументом мы получим строку с оригинальным содержимым index.html, вернуть надо модифицированный контент.

import { Plugin, ResolvedConfig } from "vite";
import path from "path";
import fs from "fs";
import { IHtmlInjectionConfig, IHtmlInjectionConfigInjection } from "./types";

export function htmlInjectionPlugin(
  htmlInjectionConfig: IHtmlInjectionConfig
): Plugin {
  let config: undefined | ResolvedConfig;

  return {
    name: "html-injection",

    configResolved(resolvedConfig) {
      config = resolvedConfig;
    },

    transformIndexHtml(html: string) {
      let out = html;
      for (let i = 0; i < htmlInjectionConfig.injections.length; i++) {
        const injection: IHtmlInjectionConfigInjection =
          htmlInjectionConfig.injections[i];

        let root = (config as ResolvedConfig).root;
        const filePath = path.resolve(root, injection.path);
        let data = fs.readFileSync(filePath, "utf8");
        if (injection.type === "js") {
          data = `<script>\n${data}\n</script>\n`;
        } else if (injection.type === "css") {
          data = `<style>\n${data}\n</style>\n`;
        }
        switch (injection.injectTo) {
          case "head":
            out = out.replace("</head>", `${data}\n</head>`);
            break;
          case "head-prepend":
            out = out.replace(/<head(.*)>/i, `$&\n${data}`);
            break;
          case "body":
            out = out.replace("</body>", `${data}\n</body>`);
            break;
          case "body-prepend":
            out = out.replace(/<body(.*)>/i, `$&\n${data}`);
            break;

          default:
            break;
        }
      }

      return out;
    },
  };
}

В массиве htmlInjectionConfig.injections содержатся описания вставляемых фрагментов кода - конфигурация плагина, передаваемая ему как аргумент в vite.config.js проекта, использующего наш плагин.

// vite.config.js
// example for Vue project

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import { htmlInjectionPlugin } from "vite-plugin-html-injection";

export default defineConfig({
  plugins: [
    vue(),
    htmlInjectionPlugin({
      // Example configuration. Can be stored in a separate json file.
      injections: [
        {
          name: "Open Graph",
          path: "./src/injections/open-graph.html",
          type: "raw",
          injectTo: "head",
        },
        {
          name: "Splash screen",
          path: "./src/injections/splash-screen.html",
          type: "raw",
          injectTo: "body-prepend",
        },
        {
          name: "Service worker",
          path: "./src/injections/sw.js",
          type: "js",
          injectTo: "head",
        },
      ],
    }),
  ]
});

В случае написания "локального" плагина для себя, вместо добавления его в devDependencies и импорта из node_modules:

import { htmlInjectionPlugin } from "vite-plugin-html-injection";

можно импортить его локально:

import { htmlInjectionPlugin } from "./src/plugins/vite-plugin-html-injection";

Типы вставляемых фрагментов кода

Существует три типа фрагментов кода, с которыми работает плагин — raw, js и css.

Raw фрагменты вставляются как есть, js и css оборачиваются в теги <script> и <style> соответственно.

Также есть четыре места, куда можно вставить фрагмент кода: начало и конец тега head и начало и конец body. Соответствующие значения свойства injectTo: head-prepend, head, body-prepend и body.

Файл ./src/injections/ga.html может выглядеть как-то так:

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-8W4X32XXXX" />
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag() {
    dataLayer.push(arguments);
  }
  gtag("js", new Date());

  gtag("config", "G-8W4X32XXXX");
</script>

Сборка плагина как пакета

В коде плагина мы используем библиотеки fs и path, которые помещать с сборку плагина не нужно, потому что они будут предоставлены самым Vite во время выполнения плагина. В vite.config.js проекта плагина это нужно указать явно.

// vite.config.js

import { defineConfig } from "vite";
import { resolve } from "path";

export default defineConfig({
  plugins: [],
  build: {
    lib: {
      entry: resolve(__dirname, "./index.ts"),
      name: "HtmlInjection",
      fileName: "index",
      formats: ["es", "cjs"],
    },
    rollupOptions: {
      external: ["fs", "path"],
    },
  },
});

В итоге размер плагина получается меньше 1КБ.

Ну и package.json плагина:

{
  "name": "vite-plugin-html-injection",
  "version": "1.1.9",
  "description": "Vite plugin for injecting html, js, css code snippets into index.html",
  "license": "MIT",
  "homepage": "https://github.com/altrusl/vite-plugin-html-injection",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    }
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "vite build && copy types.d.ts dist\\index.d.ts"
  },
  "devDependencies": {
    "@antfu/eslint-config": "^0.39.8",
    "@types/node": "^20.4.5",
    "eslint": "^8.46.0",
    "typescript": "^5.1.6",
    "vite": "^4.4.7"
  },
  "peerDependencies": {
    "vite": ">= 2.0.0"
  }
}

После сборки плагина публикуем его на npmjs.com:

npm publish --access public