Зачем я написал vite-plugin-module-alias

Мой первый публичный плагин для Vite и первый опыт написания технического поста. Не судите строго :)

Предыстория

На одном из проектов мне нужно было реализовать Telegram-бота с использованием Web App. Я выбрал стек: Vite + React + Zustand + TypeScript. До этого я в основном работал с Webpack, и столкнулся с вопросом — как удобно организовать алиасы. В Vite есть resolve.alias, и это удобно. Но дополнительно нужно прописывать пути в tsconfig.json, чтобы IDE понимала, что происходит. А ещё это не работает с HTML-импортами.

💡 Здесь важно: HTML теперь может импортировать модули напрямую, и если бы алиасы работали и там — можно было бы писать одни и те же пути и в скриптах, и в коде, и в конфиге.

Повторение — мать автоматизации

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

⚙️ Что делает плагин

Всё началось не с плагина, а с небольшой утилиты, которая брала алиасы из JSON-файла.

Зачем отдельный файл?

• Структура проектов обычно похожа;

• Хочется централизованного подхода;

• Хочется, чтобы всё сразу работало — алиасы и в vite.config.ts, и в tsconfig.json, и в HTML.

Итог: ты просто устанавливаешь плагин и копируешь import-map.json. Всё. Работает.

🔨 Начало работы над плагином

Я раньше не писал ни плагинов, ни npm-пакетов. Утилиты — да, но публиковать что-то было страшно. В этот раз решил:

«Вдруг кому-то это действительно поможет?»

Я разбил задачу на этапы и начал:

1. Поддержка import-map.json:

   • Преобразование алиасов из файла в resolve.alias.

   • Генерация тега <script type="importmap"> — это позволяет использовать алиасы и в HTML.

2. Поддержка конфигурации напрямую из объекта (без JSON-файла), если кому-то так удобнее.

Начал с самого главного — чтения JSON и генерации resolve.alias. Также генерирую блок:

<script type="importmap">

Это нужно для поддержки импортов прямо в HTML (например, в index.html в Vite).

Затем добавил поддержку передачи алиасов напрямую объектом. Вдруг кому-то JSON не подходит.

🧪 Ошибки и уроки

Когда базовая версия была готова, я быстро её опубликовал. Спойлер: так делать не надо.

Через пару дней заметил 80 скачиваний и понял — плагином пользуются. Решил протестировать глубже… и нашёл два серьёзных бага. В голове крутилась мысль:

«Блин, а вдруг кто-то уже поставил и словил их…»

Пришлось срочно чинить. На фиксы и доработку документации ушло ~10 часов.

Урок №1: не релизить, пока не уверен хотя бы на 95%.

🔄 Вторая итерация

Добавил вторую часть функционала — автоматическое обновление tsconfig.json. Это было логичным шагом: централизованная настройка должна отражаться и в TypeScript.

Пробовал использовать server.reload() внутри Vite. Но он нестабилен, так что сделал два режима:

• Автоматический — сам вызывает reload().

• Ручной — пользователю нужно самому перезапустить сервер.

🪜 Оставшаяся проблема

Пока не удалось решить проблему с потерей комментариев в tsconfig.json. JSON по стандарту не поддерживает комментарии, и парсеры их выкидывают.

Ищу варианты решения, но пока это остаётся открытым вопросом.

🧪 Тесты и первая обратная связь

У меня была тест-группа из 4 человек. Благодаря им я нашёл ещё баги и всё пофиксил. Но потом пришёл первый issue — и это было одновременно радостно и тревожно.

«Ого, кто-то не только поставил, но и написал issue!»

К счастью, это был мелкий баг, решился за 10 минут. Но сам факт — очень мотивирует.

✅ Выводы

• Делайте MVP, но тестируйте тщательно.

• Обратная связь — бесценна.

• Не бойтесь выкладывать свои инструменты — даже простой плагин может кому-то реально помочь.

🔗 Заключение

Плагин всё ещё развивается. Жду фидбека и пожеланий по фичам.

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

👉 Репозиторий: vite-plugin-module-alias (GitHub) ^[1]

Буду рад звёздочке ⭐ и issue!