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

Вам когда-нибудь требовались дополнительные возможности от конфигурации Vite, например, преобразование кастомного расширения, т.е., index.mycustomextension в index.js? Или преобразование markdown в 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: Output Plugins Stats (Вывод статистики плагинов)

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

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

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

npm init create-vite@latest

В подсказке выберите пресет Vanilla, а в качестве языка — JavaScript.

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

После этого просто сделайте остановку 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, которое является именем плагина, и специфический для Vite хук configResolved.

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: Request Analytics (Аналитика запроса)

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

Для этого добавим следующую функцию в файл 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: Hot Update Report (Отчет о горячем обновлении)

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

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

Мы можем сделать это, подключившись к хуку handleHotUpdate, как показано ниже:

vite.config.js

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

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

Хук 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. Существует бесконечное количество вариантов использования таких плагинов, и я надеюсь, что теперь у вас появится стимул создать свой собственный.

Приглашаем всех желающих на открытое занятие «Архитектура больших Vue-приложений и лучшие практики». На занятии узнаем, как можно структурировать код по мере роста приложения, про монолитную и модульную архитектуру приложения. А также:

— Обсудим, какие приемы можно применить для снижения сложности разработки и сопровождения и как нам могут помочь фабрики компонентов и сервисы.
— Разберем хорошие практики и правила хорошего стиля.
— Не забудем про антипаттерны и чего следует избегать при разработке.

Регистрация на мероприятие открыта по ссылке.

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