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

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

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

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

Проблема: хаос и неразбериха в проекте

Наверняка многие из вас знакомы с популярным плагином vite-plugin-pug. Это решение позволяет использовать Pug в проектах на базе Vite. Но у него есть существенный недостаток: необходимость создавать HTML-«обёртки» для каждой Pug-страницы.

Кажется, всё нормально, но на деле возникает ряд сложностей:

Путаница: вам нужно держать в голове, что файлы .html — это не полноценный результат, а промежуточный инструмент для сборки.

Головная боль от внесения изменений: при добавлении новых страниц или изменении структуры проекта реализация «обёрток» превращается в настоящий хардкор на больших проектах.

Ухудшение читаемости: файлы разбрасываются по проекту, и сложно быстро понять, где что находится. Каждый разработчик знает, как сложно поддерживать цельную архитектуру на масштабных проектах, избегая появления «мусорных» файлов и избыточной вложенности.

Так перед нами остро встала задача создания удобной и прозрачной системы, исключающей вышеописанные проблемы.

Решение: рендерим Pug напрямую

«Если готовое решение не устраивает, кто мешает создать собственное?» — подумал я, наткнувшись на очередной структурный хаос. К счастью, у нас в Mish к таким инициативам относятся с энтузиазмом: мы поддерживаем и развиваем идеи друг друга. Это помогает не только в достижении личных целей, но и улучшает жизнь всей команды.

Оказалось, для решения проблемы нужны всего две вещи:

API Pug для преобразования .pug в HTML.
Сборщик Vite для интеграции с рабочим процессом.

Так началась моя работа над плагином vite-convert-pug-in-html.

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

Вместо создания избыточных файлов, мой плагин:

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

Как это работает

С помощью API Pug и хука сборки Vite плотно интегрируем процесс рендеринга .pug в HTML-файлы.
Устраняем необходимость использовать «обёртки»: больше никаких .html, только .pug файлы.
Добавляем поддержку HMR. Любое изменение в .pug моментально обновляет страницу.

Для версии до 1.21.1 включительно настройка плагина происходит так

import { defineConfig } from 'vite';
import { viteConvertPugInHtml } from '@mish.dev/vite-convert-pug-in-html';

export default defineConfig({
  plugins: [
    viteConvertPugInHtml({
      pages: {
        index: 'src/index.pug',
      },
      replacement: {
        script: '/scripts/main.js',
        css: 'style.css',
      },
    }),
  ],
  build: {
    rollupOptions: {
      input: {
        main: 'scripts/main.ts',
      },
    },
  },
});

Для версии 2.0.0 нам ничего не надо настраивать, достаточно вызвать плагин

import { defineConfig } from 'vite';
import { viteConvertPugInHtml } from '@mish.dev/vite-convert-pug-in-html';

export default defineConfig({
  root: 'src',

  plugins: [
    viteConvertPugInHtml(),
  ],

  build: {
    outDir: '../dist',
  },
});

Чем полезен плагин

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

1. Простая структура проекта

Больше никаких громоздких HTML-обёрток, .pug автоматически превращается в красивый HTML без лишних «костылей». Все страницы хранятся в одном месте с очевидной вложенностью.

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

2. Горячая замена модулей (HMR)

Каждое ваше изменение в .pug мгновенно отображается в браузере. Это существенно ускоряет процесс отладки. Забудьте о перезагрузке страницы, автообновление – наше всё.

3. Прощайте «хвосты» у URL

Благодаря плагину, в продакшене ваши страницы будут выглядеть аккуратно: вместо https://example.com/about.htm будет https://example.com/about. Это идеально для SEO и удобного пользовательского опыта.

4. Экономия времени

Вы больше не тратите время на настройку путей для CSS и JS. Все ссылки меняются автоматически на нужные, плагин делает это за вас.

5. Поддержка алиасов

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

Почему мы делимся этим решением

Open source для нас в Mish — это не только про код, но и про культуру. Делимся тем, что облегчает работу, экономит время и делает процесс разработки комфортным. Потому что мы сами такими инструментами пользуемся каждый день.

Плагин vite-convert-pug-in-html — наша внутренняя разработка, которая так хорошо себя зарекомендовала, что мы решили ею поделиться. Нам важно, чтобы и другие разработчики чувствовали то же удобство, которое теперь есть у нас.

Как установить?

Если работа с Pug и Vite доставляла вам столько же хлопот, сколько когда-то мне, тогда попробуйте плагин vite-convert-pug-in-html чтобы избавиться от этой головной боли. Он упрощает жизнь, ускоряет работу и избавляет от рутины.

Установите плагин через npm. npm install @mish.dev/vite-convert-pug-in-html
Настройте vite.config.js, как в примере выше.
Всё готово! Запускайте проект и легко настраивайте структуру.

Для более подробного изучения плагина, включая все доступные настройки и конфигурации, загляните в документацию на npm или в репозиторий на GitHub.

Меньше ручной работы, больше времени на главное

Работа с Pug и Vite может и должна быть простой, без хаоса и лишних обходных путей. Для Mish этот плагин стал тем самым недостающим элементом, который позволил нам навести порядок в структуре. Теперь мы экономим время, ресурсы и внимание команды, фокусируясь на решении ключевых задач.

Если вы хотите оптимизировать свои процессы, сократить операционные затраты и вывести разработку на новый уровень эффективности, опробуйте плагин на своих проектах.

Не тратьте ресурсы на борьбу с неудобством, выбирайте инструменты, которые работают за вас.

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