метла верстка.png

Привет, я Андрей Беннер, фронтенд-разработчик в Mish. Сейчас я расскажу вам о нашем опыте в оптимизации хаотичных процессов с помощью собственных разработок. 
Если вы когда-либо работали с проектами на стеке Vite + Pug + SCSS + TypeScript, то наверняка сталкивались с хаосом в файловой структуре и рутиной, мешающей сосредоточиться на главном — решении задач бизнеса и создании удобного интерфейса для пользователя. 

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

<h3>Проблема: хаос и&nbsp;неразбериха в&nbsp;проекте</h3>
<p>Наверняка многие из&nbsp;вас знакомы с&nbsp;популярным плагином vite-plugin-pug. Это решение позволяет использовать Pug в&nbsp;проектах на&nbsp;базе Vite. Но&nbsp;у&nbsp;него есть существенный недостаток: необходимость создавать HTML-&laquo;обёртки&raquo; для каждой Pug-страницы.</p>
&nbsp;

<img src="/uploads/vc_1_1_a67f775187.png">

<p>Кажется, всё нормально, но&nbsp;на&nbsp;деле возникает ряд сложностей:</p>

<p><em>Путаница:</em> вам нужно держать в&nbsp;голове, что файлы .html&nbsp;&mdash; это не&nbsp;полноценный результат, а&nbsp;промежуточный инструмент для сборки.</p>

<p><em>Головная боль от&nbsp;внесения изменений:</em> при добавлении новых страниц или изменении структуры проекта реализация &laquo;обёрток&raquo; превращается в&nbsp;настоящий хардкор на&nbsp;больших проектах.</p>

<p><em>Ухудшение читаемости:</em> файлы разбрасываются по&nbsp;проекту, и&nbsp;сложно быстро понять, где что находится. Каждый&nbsp;разработчик знает, как сложно поддерживать цельную архитектуру на&nbsp;масштабных проектах, избегая&nbsp;появления &laquo;мусорных&raquo; файлов и&nbsp;избыточной вложенности.</p>

<p>Так перед нами остро встала задача создания удобной и&nbsp;прозрачной системы, исключающей вышеописанные проблемы</p>

<h3>Решение: рендерим Pug напрямую</h3>
<p><p><em>&laquo;Если готовое решение не&nbsp;устраивает, кто мешает создать собственное?&raquo;</em></p>
 &nbsp;&mdash; подумал&nbsp;я, наткнувшись на&nbsp;очередной структурный хаос. К&nbsp;счастью, у&nbsp;нас в&nbsp;Mish к&nbsp;таким инициативам относятся с&nbsp;энтузиазмом: мы&nbsp;поддерживаем и&nbsp;развиваем идеи друг друга. Это помогает не&nbsp;только в&nbsp;достижении личных целей, но&nbsp;и&nbsp;улучшает жизнь всей команды.</p>

<p>Оказалось, для решения проблемы нужны всего две вещи:</p>
<ul>
  <li>API Pug для преобразования .pug в&nbsp;HTML.</li>
  <li>Сборщик Vite для интеграции с&nbsp;рабочим процессом.</li>
</ul>
<p>Так началась моя работа над плагином vite-convert-pug-in-html.</p>

<h3>Что делает плагин</h3>
<p>Вместо создания избыточных файлов, мой плагин:</p>
<ul>
  <li>Рендерит .pug файлы напрямую в&nbsp;HTML&nbsp;на этапе сборки.</li>
  <li>Формирует понятную структуру итоговых файлов (например, about.pug превращается в&nbsp;pages/about/index.html).</li>
  <li>Упрощает работу с&nbsp;dev-сервером: каждый запрос .html перехватывается, ищется соответствующий .pug, и&nbsp;страница рендерится прямо на&nbsp;лету.</li>
  <li>Настраивает правильные пути к&nbsp;CSS и&nbsp;JS-ассетам в&nbsp;итоговом HTML (никаких танцев с&nbsp;бубном!).</li>
</ul>

<p>Как это работает</p>
<ul>
  <li>С&nbsp;помощью API Pug и&nbsp;хука сборки Vite плотно интегрируем процесс рендеринга .pug в&nbsp;HTML-файлы.</li>
  <li>Устраняем необходимость использовать &laquo;обёртки&raquo;: больше никаких .html, только .pug файлы.</li>
  <li>Добавляем поддержку HMR. Любое изменение в .pug моментально обновляет страницу.</li>
</ul>

<p>Для версии до&nbsp;1.21.1 включительно настройка плагина происходит так</p>

<img src="/uploads/vc_2_d1b002b241.png">

<p>Для версии 2.0.0 нам ничего не&nbsp;надо настраивать, достаточно вызвать плагин</p>

<img src="/uploads/photo_2025_08_27_23_16_04_7e3ba5a4c6.jpg">

<h3>Чем полезен плагин</h3>
<p>Теперь, давайте разберёмся, почему vite-convert-pug-in-html стал неотъемлемой частью нашего рабочего процесса и&nbsp;какое влияние он&nbsp;может оказать на&nbsp;ваши проекты.</p>

<p><strong>1. Простая структура проекта</strong></p>
<p>Больше никаких громоздких HTML-обёрток, .pug автоматически превращается в&nbsp;красивый HTML без лишних &laquo;костылей&raquo;. Все страницы хранятся в&nbsp;одном месте с&nbsp;очевидной вложенностью.</p>

<img src="/uploads/vc_3_d122210d6d.png">

<p>Это особенно полезно на&nbsp;больших проектах, где сотни файлов могут запутать даже опытных девелоперов.</p>

<p><strong>2. Горячая замена модулей (HMR)</strong></p>
<p>Каждое ваше изменение в .pug мгновенно отображается в&nbsp;браузере. Это существенно ускоряет процесс отладки. Забудьте о&nbsp;перезагрузке страницы, автообновление&nbsp;&mdash; наше всё.</p>

<p><strong>3. Прощайте «хвосты» у URL</strong></p>
<p>Благодаря плагину, в&nbsp;продакшене ваши страницы будут выглядеть аккуратно: вместо https://example.com/about.htm будет https://example.com/about. Это идеально для SEO и&nbsp;удобного пользовательского опыта.</p>

<p><strong>4. Экономия времени</strong></p>
<p>Вы&nbsp;больше не&nbsp;тратите время на&nbsp;настройку путей для CSS и&nbsp;JS. Все ссылки меняются автоматически на&nbsp;нужные, плагин делает это за&nbsp;вас.</p>

<p><strong>5. Поддержка алиасов</strong></p>
<p>Вы&nbsp;больше не&nbsp;тратите время на&nbsp;относительные пути. Достаточно указать алиасы в&nbsp;конфиге vite и&nbsp;использовать их&nbsp;в .pug файлах.</p>

<h3>Почему мы&nbsp;делимся этим решением</h3>
<p>Open source для нас в&nbsp;Mish&nbsp;&mdash; это не&nbsp;только про код, но&nbsp;и&nbsp;про культуру. Делимся тем, что облегчает работу, экономит время и&nbsp;делает процесс разработки комфортным. Потому что мы&nbsp;сами такими инструментами пользуемся каждый день.
Плагин&nbsp;vite-convert-pug-in-html&nbsp;&mdash;&nbsp;наша&nbsp; внутренняя разработка, которая так хорошо себя зарекомендовала, что мы&nbsp;решили ею&nbsp;поделиться. Нам важно, чтобы и&nbsp;другие разработчики чувствовали то&nbsp;же удобство, которое теперь есть у&nbsp;нас.</p>
</div>

<h3>Как установить?</h3>
<p>Если работа с&nbsp;Pug и&nbsp;Vite доставляла вам столько&nbsp;же хлопот, сколько когда-то мне, тогда попробуйте плагин vite-convert-pug-in-html чтобы избавиться от&nbsp;этой головной боли. Он&nbsp;упрощает жизнь, ускоряет работу и&nbsp;избавляет от&nbsp;рутины.</p>
<ul>
  <li>Установите плагин через npm. 
npm install @mish.dev/vite-convert-pug-in-html</li>
  <li>Настройте vite.config.js, как в&nbsp;примере выше.</li>
  <li>Всё готово! Запускайте проект и&nbsp;легко настраивайте структуру.</li>
</ul>
<p>Для более подробного изучения плагина, включая все доступные настройки и&nbsp;конфигурации, загляните в&nbsp;документацию на&nbsp;npm или в&nbsp;репозиторий на&nbsp;GitHub.</p>

<h3>Меньше ручной работы, больше времени на&nbsp;главное</h3>
<p>Работа с&nbsp;Pug и&nbsp;Vite может и&nbsp;должна быть простой, без хаоса и&nbsp;лишних обходных путей. Для Mish этот плагин стал тем самым недостающим элементом, который позволил нам навести порядок в&nbsp;структуре. Теперь мы&nbsp;экономим время, ресурсы и&nbsp;внимание команды, фокусируясь на&nbsp;решении ключевых задач.</p>
<p>Если вы&nbsp;хотите оптимизировать свои процессы, сократить операционные затраты и&nbsp;вывести разработку на&nbsp;новый уровень эффективности, опробуйте плагин на&nbsp;своих проектах.</p>
<p>Не&nbsp;тратьте ресурсы на&nbsp;борьбу с&nbsp;неудобством, выбирайте инструменты, которые работают за&nbsp;вас.</p>

Как мы решили проблему хаотичной структуры проекта с Pug и Vite

Беннер Андрей

залипающий ховер.png

Залипающий hover на мобильных устройствах – частый баг. Раньше мы решали это просто плагином PostCSS Hover Media Feature, он оборачивает все псевдоклассы :hover в медиазапрос @media (hover: hover) {}. Так мы проверяли поддержку hover и отключали его на мобилках.
Но во время тестирования одного проекта оказалось, что на некоторых устройствах hover продолжает залипать.

<h3>Первая теория: плагин работает некорректно</h3>

<p>Что мы&nbsp;проверили:</p>
<ul>
  <li>Плагин не&nbsp;оборачивает правила?
Нет, всё&nbsp;ок. После сборки <code>hover</code> был в&nbsp;медиазапросах.</li>
  <li>Не&nbsp;работает <code>hover: hover?</code>
Проверили в&nbsp;эмуляции мобильных устройств&nbsp;&mdash; работает.</li>
</ul>

<p>Значит, проблема не&nbsp;в&nbsp;плагине.</p>
&nbsp;

<h3>Вторая теория: баг на&nbsp;отдельных устройствах</h3>

<p>Мы&nbsp;начали тестировать разные модели через Browserstack. На&nbsp;большинстве устройств всё нормально, но&nbsp;есть&nbsp;одно&nbsp;но.</p>

<p>Samsung Galaxy игнорирует всё.</p>
<p>Ему всё равно, что мы&nbsp;оборачиваем <code>hover</code> в <code>@media (hover: hover)</code>. Он&nbsp;отвечает: &laquo;Да-да, я&nbsp;поддерживаю <code>hover</code>&raquo;, а&nbsp;потом предательски залипает.</p>

<p>Дальнейшая проверка показала, что дело не&nbsp;только в&nbsp;Galaxy. Похожая история случается и&nbsp;на&nbsp;некоторых моделях Vivo.</p>

<img src="/uploads/vc_2_2_724c99934a.png"> 

<p>В&nbsp;процессе поиска ответов мы&nbsp;наткнулись на&nbsp;<a href="https://habr.com/ru/companies/ruvds/articles/556156/">интересную статью</a> о&nbsp;том, как определять устройства с&nbsp;тачскрином&nbsp;на&nbsp;чистом CSS. Такой способ удобен и&nbsp;для SSR, поэтому мы&nbsp;его изучили. Были варианты и&nbsp;с&nbsp;хуками, но&nbsp;они работают только на&nbsp;клиенте.</p>
&nbsp;

<h3>Как проверить вашу мобилку</h3>

<p>Если интересно, вот ссылки, чтобы прогнать ваши устройства:</p>
<ul>
  <li><a href="https://developer.chrome.com/docs/devtools/remote-debugging?hl=ru">Подключение Android к Chrome DevTools</a></li>
  <li><a href="https://www.browserstack.com/docs/live/local-testing/set-up-local-testing">Локальное тестирование через Browserstack</a></li>
</ul>
&nbsp;

<h3>Глубже в&nbsp;проблему: откуда берётся true?</h3>

<p>Возникает логичный вопрос: как браузер определяет, что событие hover поддерживается?</p>

<p>Мы&nbsp;обратились к&nbsp;исходникам Chromium. Там есть файл <a href="https://github.com/chromium/chromium/blob/main/ui/events/event.cc">event.cc</a>, где перечислены все события. В&nbsp;нём&nbsp;видно:&nbsp;браузер&nbsp;получает события от&nbsp;ОС.</p>

<p>А&nbsp;в&nbsp;файле <a href="https://github.com/chromium/chromium/blob/main/ui/events/platform_event.h">platform_event.h</a> можно заметить, что тип события зависит от&nbsp;платформы (Windows, Mac, iOS, Linux).</p>

<p>То&nbsp;есть:</p>
<ul>
  <li>Аппаратная часть устройства сообщает&nbsp;ОС, что за&nbsp;событие произошло.</li>
  <li>ОС&nbsp;передаёт его браузеру через драйверы и&nbsp;обработчики.</li>
  <li>Браузер преобразует его в&nbsp;знакомые нам события, с&nbsp;которыми мы&nbsp;работаем.</li>
</ul>

<p>Отсюда и&nbsp;ответ: если устройство сообщает, что <code>hover</code> есть, браузер возвращает <code>true</code> на <code>window.matchMedia(&rsquo;(hover: hover)&rsquo;).</code></p>
&nbsp;

<h3>MDN и&nbsp;медиазапрос pointer</h3>

<p>На&nbsp;MDN мы&nbsp;нашли медиазапрос <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@media/pointer">pointer</a>. Он&nbsp;определяет, какое устройство ввода подключено:</p>
<ul>
  <li><code>fine</code>&nbsp;&mdash; точное устройство (мышь, тачпад, стилус).</li>
  <li><code>coarse</code>&nbsp;&mdash; неточное (палец).</li>
</ul>
&nbsp;

<p>Проверить это можно так:</p>

<pre><code>window.matchMedia('(pointer: coarse)');</code></pre>
<pre><code>window.matchMedia(&rsquo;(pointer: fine)&rsquo;).</code></pre>

<p>Метод возвращает объект с&nbsp;полем <code>matches</code>, где и&nbsp;видно, какое устройство ввода сейчас активно.</p>
&nbsp;

<h3>Почему pointer: fine недостаточно</h3>

<p>На&nbsp;первый взгляд кажется: давайте использовать только <code>pointer: fine</code> и&nbsp;забудем про hover. Но&nbsp;не&nbsp;всё&nbsp;так&nbsp;просто.</p>
<ul>
  <li>У&nbsp;некоторых устройств <code>pointer: fine</code> возвращает <code>true</code>, но&nbsp;<code>hover</code> они не&nbsp;поддерживают.</li>
  <li>Стилусы иногда определяются как <code>fine</code>, но&nbsp;тоже не&nbsp;имеют hover.</li>
</ul>
&nbsp;

<p>Поэтому мы&nbsp;должны проверять оба условия:</p>
<p><code>@media (hover: hover) and (pointer: fine) { ... }</code></p>
&nbsp;

<h3>А&nbsp;как&nbsp;же спецификация?</h3>

<img src="/uploads/vc_1_2_89fc7a853f.png"> 

<p>Если обратиться к&nbsp;<a href="https://www.w3.org/TR/mediaqueries-4/#pointer">спеке W3C</a>, то&nbsp;там есть важное уточнение. Даже если устройство имеет <code>pointer: coarse</code>, это&nbsp;не&nbsp;значит, что точные клики невозможны. Это говорит о&nbsp;том, что мы&nbsp;можем совершать точные клики при&nbsp;помощи того&nbsp;же стилуса.</p>
<p>Иными словами: медиазапросы дают разработчику лишь подсказку о&nbsp;том, как лучше строить интерфейс, а&nbsp;не&nbsp;жёсткую гарантию.</p>
&nbsp;

<h3>Решение:</h3>

<p>Мы&nbsp;пришли к&nbsp;следующему варианту: используем медиазапрос <code>(hover: hover) and (pointer: fine)</code>, чтобы&nbsp;hover-стили&nbsp;применялись&nbsp;только&nbsp;на&nbsp;устройствах с&nbsp;мышью или тачпадом.</p>

<p>Варианты внедрения</p>
<ul>
  <li>Обернуть стили вручную. Подходит для небольших проектов.</li>
  <li>Допилить оригинальный плагин.</li>
  <li>Написать свой.</li>
</ul>

<p>Так как в&nbsp;репозитории оригинального плагина давно висят нерешённые реквесты, мы&nbsp;решили не&nbsp;ждать и&nbsp;сделать свой.</p>
&nbsp;

<h3>Наш плагин</h3>

<p>Когда стало ясно, что простого <code>hover: hover</code> недостаточно, мы&nbsp;решили создать свой плагин.</p>

<p>Чтобы сделать использование плагина удобнее и&nbsp;безопаснее, мы&nbsp;сделали версию на&nbsp;<a href="https://github.com/Hwaiteu/postcss-media-hover-fix">TypeScript</a>.</p>

<p>Это дало:</p>
<ul>
  <li>Чёткую типизацию входных и&nbsp;выходных данных;</li>
  <li>Упрощённое отлавливание ошибок на&nbsp;этапе разработки;</li>
  <li>Более структурный и&nbsp;понятный код для будущих изменений.</li>
</ul>

<p>Теперь у&nbsp;нас есть &laquo;боевая&raquo; версия плагина, которую можно смело подключать в&nbsp;проект и&nbsp;не&nbsp;переживать за&nbsp;<code>hover</code> на&nbsp;мобильных устройствах.</p>
&nbsp;

<h3>Итог</h3>

<p>История с&nbsp;залипающим hover показала: полагаться только на&nbsp;hover: hover не&nbsp;стоит&nbsp;&mdash; иногда он&nbsp;&laquo;залипает&raquo; и&nbsp;слегка раздражает пользователя, хотя интерфейс при этом и&nbsp;не&nbsp;ломается.</p>

<p>С&nbsp;нашим решением hover остаётся только там, где он&nbsp;действительно нужен, а&nbsp;&laquo;притворщики&raquo; типа тачскринов больше не&nbsp;вмешиваются.</p>

<p>В&nbsp;результате мы&nbsp;получили полезный и&nbsp;интересный опыт в&nbsp;автоматическом оборачивании hover в&nbsp;медиазапросы с&nbsp;более полным условием. Залипающий hover больше не&nbsp;раздражает, а&nbsp;ручное прописывание условий стало не&nbsp;нашей головной болью&nbsp;&mdash; так&nbsp;мы (а&nbsp;теперь и&nbsp;вы) можем чуть расслабиться и&nbsp;довериться автоматике.</p>

Беннер Андрей

Бриф сам себя не заполнит

hello@mish.design

Москва

Нижний Новгород