Создание плагина с 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 г.