Создание плагина с Vite

Автор: Келвин О Омерешон

Зачем создавать плагин Vite

Вам когда-нибудь требовались дополнительные возможности конфигурации Vite, например разрешение пользовательского расширения, например, с index.mycustomextension на index.js? Или конвертировать уценку в JSX?

Плагин Vite позволяет нам выполнять подобные задачи. Так что вам может быть интересно, как создать плагин Vite самостоятельно. В этой статье мы рассмотрим, как создать несколько простых плагинов, которые вы можете использовать в качестве основы и вдохновения для своих собственных плагинов Vite.

Что такое плагин Vite?

Плагин Vite — это плагин Rollup с некоторыми параметрами и хуками, характерными для Vite, которые позволяют добавлять пользовательские функции поверх Vite для решения конкретной проблемы. Например, Astro использует плагин Vite для разрешения .astro файлов.

Плагин Vite — это объект с одним или несколькими:

const vitePluginExample = () => ({
	// properties
  name: 'vite-plugin-example', 
	// build hooks
  config: () => ({
    resolve: {
      alias: {
        foo: 'bar'
      }
    }
  }),
	// output generation hooks
	augmentChunkHash(chunkInfo) {
      if (chunkInfo.name === 'bar') {
        return Date.now().toString();
      }
    }
})

Давайте кратко коснемся этих трех компонентов плагина Vite, прежде чем научиться создавать собственные файлы .

Характеристики

Единственным обязательным свойством плагина Vite является свойство name, которое является именем плагина. Это необходимо, потому что это полезно для отладки и сообщений об ошибках.

Строить крючки

Это основной способ взаимодействия плагина с процессом сборки Vite. Хуки — это функции, которые вызываются на разных этапах сборки. Вы можете использовать хуки, чтобы изменить способ запуска сборки, собрать информацию о сборке или изменить сборку после ее завершения.

Хуки генерации вывода

Эти хуки можно использовать для предоставления информации о сгенерированном пакете и изменения сборки после ее завершения.

Создание плагина Vite

Приступить к созданию подключаемого модуля Vite так же просто, как указать фабричную функцию в файле vite.config.js. Эта функция вернет фактический объект плагина, который содержит все определения и логику плагина. Затем вы можете передать эту функцию массиву plugins в объекте defineConfig.

Примечание. Это обычная функция, и поэтому она может принимать параметры, которые позволяют настраивать поведение плагина в пользовательской среде.

Чтобы познакомить вас с созданием плагинов, мы создадим три простых плагина, чтобы показать вам, как выглядит создание плагина Vite.

Начнем с первого.

Пример №1: вывод статистики плагинов

Что может быть лучше примера «привет, мир», чем создание плагина, который выводит статистику о плагинах в вашем проекте Vite?

Этот плагин будет работать следующим образом: когда вы запустите npm run dev, вы должны увидеть вывод output-plugin-stats хука, который будет представлять собой количество плагинов в вашем проекте и таблицу всех плагинов. Итак, мета.

Чтобы создать это, давайте сначала создадим проект Vanilla Vite, выполнив эту команду в вашем терминале:

npm init create-vite@latest

В приглашении выберите предустановку Vanilla и JavaScript в качестве языка.

Затем запустите npm install и npm run dev, чтобы убедиться, что установка прошла успешно.

Как только это будет сделано, просто завершите сервер разработки и создайте файл vite.config.js в корне вашего проекта и добавьте этот код:

📄 vite.config.js

import { defineConfig } from 'vite'
export default defineConfig({
  plugins: []
})

Теперь у нас есть скелет для конкретизации функциональности нашего плагина, который мы передадим в массив plugins.

📄 vite.config.js

import { defineConfig } from 'vite'
const outputPluginStats = () => ({
  name: 'output-plugin-stats',
  configResolved(config) {
    const plugins = config.plugins.map((plugin) => plugin.name)
    console.log(`Your project has ${plugins.length} Vite plugins.`)
    console.table(plugins)
  }
})
export default defineConfig({
  plugins: [
    outputPluginStats()
  ]
})

Как видите, у нас есть функция outputPluginStats, которая возвращает объект со свойством name, которое является именем плагина, и хук configResolved, специфичный для Vite.

configResolved вызывается после того, как конфигурация Vite была разрешена, и вы можете использовать ее для чтения и сохранения окончательной разрешенной конфигурации.

Давайте посмотрим, что мы делаем в приведенном выше коде:

const plugins = config.plugins.map((plugin) => plugin.name)

Мы сопоставляем плагины в config.plugins и возвращаем имена плагинов в виде массива с именем plugins.

console.log(`Your project has ${plugins.length} Vite plugins.`)

Приведенная выше строка выводит количество плагинов в массиве plugins, используя Array.prototype.length.

Наконец, мы выводим массив plugins в таблицу:

console.table(plugins)

После того, как мы определили плагин, мы регистрируем плагин в массиве plugins объекта конфигурации Vite:

export default defineConfig({
  plugins: [
    outputPluginStats()
  ]
})

Пример № 2: Запросить аналитику

В нашем следующем примере мы добавим промежуточное программное обеспечение — функцию, которая будет выполняться до того, как сервер обработает запрос — к базовому серверу Vite connect для регистрации запросов, которые обрабатывает сервер.

Для этого добавим следующую функцию в наш файл vite.config.js.

📄 vite.config.js

const requestAnalytics = () => ({
  name: 'request-analytics',
  configureServer(server) {
    return () => {
      server.middlewares.use((req, res, next) => {
        console.log(`${req.method.toUpperCase()} ${req.url}`)
        next()
      })
    }
  }
})

В приведенном выше плагине мы используем хук configureServer для добавления промежуточного программного обеспечения на сервер Vite.

Давайте углубимся в то, что делает каждая строка приведенного выше кода.

Во-первых, мы устанавливаем имя плагина.

name: 'request-analytics'

Затем хук configureServer позволяет нам настроить сервер Vite:

configureServer(server) {
    return () => {
     
    }
  }

Затем мы добавляем промежуточное ПО, которое принимает 3 аргумента: req, res, next. Внутри промежуточного программного обеспечения мы регистрируем метод запроса и запрошенный URL.

configureServer(server) {
    return () => {
      server.middlewares.use((req, res, next) => {
        console.log(`${req.method.toUpperCase()} ${req.url}`)
        next()
      })
    }
  }

Наконец, мы передаем запрос следующему обработчику с вызовом next().

Мы будем вызывать плагин в массиве plugins, например:

📄 vite.config.js

export default defineConfig({
  plugins: [
    outputPluginStats(),
    requestAnalytics()
  ]
})

Теперь, когда мы запускаем сервер Vite, запустив npm run dev и посетив http://localhost:5173/, мы должны увидеть следующий вывод:

GET /index.html

Мы только что создали своего рода аналитику запросов, которая сообщает нам, какие файлы обслуживались сервером Vite.

Пример №3: Отчет о горячем обновлении

Для нашего последнего примера… Допустим, мы хотим сообщить о модулях, которые были обновлены во время горячей замены модуля, внутри консоли.

Для этого создадим плагин под названием hotUpdateReport.

Мы можем сделать это, нажав на хук handleHotUpdate, вот так:

📄 vite.config.js

const hotUpdateReport = () => ({
  name: 'hot-update-report',
  handleHotUpdate({file, timestamp, modules}) {
    console.log(`${timestamp}: ${modules.length} module(s) updated`)
  }
})

Обратите внимание, что мы используем хук handleHotUpdate для регистрации метки времени, а также количества обновленных модулей.

Хук handleHotUpdate предоставляет объект HmrContext, который мы деструктурируем, чтобы получить от него свойства file, timestamp и modules.

Нам просто нужно зарегистрировать плагин, например:

📄 vite.config.js

export default defineConfig({
  plugins: [
    outputPluginStats(),
    requestAnalytics(),
    hotUpdateReport()
  ]
})

Теперь, когда мы обновим index.html, main.js или style.css, мы получим отчет в нашей консоли.

Публикация плагина Vite

Если после создания вашего плагина вы решите, что хотите поделиться им как отдельным пакетом, который будет установлен через NPM, вы должны следовать этим соглашениям:

  • У вашего плагина должно быть понятное имя с префиксом vite-plugin-.
  • Включить ключевое слово vite-plugin в package.json
{
  "name": "building-a-plugin-with-vite",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "keywords": ["vite-plugin"],
}
  • При документировании вашего плагина включите раздел с подробным описанием того, почему это только плагин Vite (а не плагин Rollup). Распространенная причина того, что плагин предназначен только для Vite, заключается в том, что он использует некоторые специфические для Vite хуки плагинов.
  • Наконец, если ваш плагин работает только для определенного фреймворка, имя фреймворка должно быть частью префикса имени плагина, например, vite-plugin-svelte-, vite-plugin-react-, vite-plugin-react-, vite-plugin-lit- и т. д.

Куда пойти отсюда?

Благодаря этим примерам у вас теперь есть основные строительные блоки для создания собственных плагинов Vite. Существует бесконечное количество вариантов использования таких плагинов, и я надеюсь, что теперь вы чувствуете вдохновение для создания своего собственного.

Если вам интересно углубиться в Vite, ознакомьтесь с курсом Vue Mastery Молниеносные сборки с Vite, который преподает создатель Vite Эван Ю.

Первоначально опубликовано на https://www.vuemastery.com 8 ноября 2022 г.