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

Зачем создавать плагин 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 (а не для Rollup). Чаще всего плагин предназначен только для Vite, потому что он использует некоторые специфические для Vite хуки плагина.

• Наконец, если ваш плагин работает только для определенного фреймворка, то его название должно быть частью префикса названия плагина, например, vite-plugin-svelte-, vite-plugin-react-, vite-plugin-react-, vite-plugin-lit- и т.д.

Куда двигаться дальше?

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

---

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

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

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