templates/webpunk-templates

Webpunk Templates — Подробная документация по сборщику

Быстрый старт

1. Установите pnpm:
   Инструкция по установке

2. Установите зависимости:

   pnpm install
   

3. Запустите сборку или сервер разработки:

   • Сборка:

     pnpm run build
     

   • Сервер разработки:

     pnpm run dev
     

---

Структура проекта

• src/ — исходные файлы (шаблоны, стили, скрипты, изображения, данные)
• dist/ — результат сборки (готовый к публикации код)
• ssl/ — dev SSL-сертификаты (создаются автоматически)
• .env.local — локальная конфигурация сборщика

---

Основные возможности сборщика

1. Гибкая работа с шаблонами

• Поддержка Pug и Twig (выбор через .env.local или команды)
• Инкрементальная сборка страниц: при изменении страницы пересобирается только она
• Автоматическая подгрузка данных из src/data/*.json для шаблонов
• В шаблонах доступны функции для генерации srcset и mime-типов изображений

2. Стили и скрипты

• SCSS компиляция с sourcemaps, autoprefixer, postcss-url (автоматическое добавление версий к ассетам)
• Минификация CSS (style.min.css)
• Сборка и минификация JS (разделение на common/vendor)
• Поддержка sourcemaps для JS

3. Изображения

• Оптимизация PNG, JPEG, SVG
• Генерация webp и avif-версий изображений
• Инкрементальная обработка (обрабатываются только новые/изменённые файлы)
• Генерация SVG-спрайта и автоматическая инъекция в HTML

4. Автоматизация и наблюдение

• Watch-режим для всех исходников (шаблоны, данные, стили, скрипты, изображения, иконки)
• При изменении страницы пересобирается только она, при изменении общих файлов — пересобираются все страницы
• Автоматическая перезагрузка браузера через BrowserSync

5. HTTPS для разработки

• Автоматическое создание самоподписанных SSL-сертификатов для локальной разработки
• Включение HTTPS через .env.local или специальные команды

6. Конфигурация

• Все параметры (шаблонизатор, порт, хост, HTTPS, автооткрытие браузера и др.) настраиваются в .env.local
• Быстрое создание и обновление конфигурации через команды

---

Основные команды

Команда	Описание
pnpm run dev	Запуск сервера разработки (шаблонизатор по умолчанию из .env.local)
pnpm run dev:pug	Запуск dev-сервера с Pug
pnpm run dev:twig	Запуск dev-сервера с Twig
pnpm run dev:https	Dev-сервер с HTTPS
pnpm run dev:pug:https	Dev-сервер с Pug и HTTPS
pnpm run dev:twig:https	Dev-сервер с Twig и HTTPS
pnpm run build	Сборка проекта (шаблонизатор по умолчанию)
pnpm run build:pug	Сборка с Pug
pnpm run build:twig	Сборка с Twig
pnpm run ssl:create	Создать dev SSL-сертификаты
pnpm run ssl:check	Проверить наличие SSL-сертификатов
pnpm run ssl:info	Информация о сертификатах
pnpm run ssl:delete	Удалить dev SSL-сертификаты
pnpm run data:create	Создать пример файла данных
pnpm run config:create	Создать .env.local с настройками
pnpm run config:reload	Перезагрузить конфиг без перезапуска сервера
pnpm run clean	Очистить папку dist
pnpm run pugprettier:fix	Применить prettier к pug-файлам
pnpm run stylelint	Проверить SCSS на ошибки
pnpm run stylelint:fix	Исправить ошибки SCSS автоматически
pnpm run eslint	Проверить JS на ошибки
pnpm run gh-pages	Залить содержимое dist на GitHub Pages
pnpm run public	Сборка и публикация на GitHub Pages

---

Как работает сборщик

1. Конфигурация
   При запуске читается .env.local. Если файла нет — создаётся автоматически.
   Можно выбрать шаблонизатор, порт, хост, включить HTTPS и др.

2. Сборка

   • Очищается папка dist
   • Копируются ассеты (шрифты, изображения, фавиконки, robots.txt и др.)
   • Компилируются стили и скрипты (с минификацией и sourcemaps)
   • Оптимизируются изображения, генерируются webp/avif
   • Генерируется SVG-спрайт
   • Собираются HTML-файлы из шаблонов (Pug или Twig), подставляются данные из JSON
   • В HTML автоматически инъектируется SVG-спрайт

3. Dev-сервер

   • Запускается BrowserSync на выбранном порту/хосте
   • При изменении страницы пересобирается только она (инкрементальная сборка)
   • При изменении общих файлов (layout, mixins, data) пересобираются все страницы
   • При изменении ассетов, стилей, скриптов — пересобираются только они
   • Браузер автоматически перезагружается

4. HTTPS

   • При первом запуске с HTTPS создаются dev-сертификаты (openssl обязателен)
   • Сервер работает по https://

---

Примеры использования

• Сменить шаблонизатор:
  В .env.local изменить TEMPLATE_ENGINE=pug или TEMPLATE_ENGINE=twig, либо использовать команды dev:pug, dev:twig, build:pug, build:twig.

• Включить HTTPS:
  В .env.local поставить HTTPS=true или использовать команду dev:https.

• Добавить новые данные:
  Добавьте JSON-файл в src/data/, он автоматически попадёт в шаблоны.

---

Советы

• Для корректной работы HTTPS нужен установленный openssl.
• Для публикации на GitHub Pages используйте pnpm run public.
• Для быстрой генерации структуры данных используйте pnpm run data:create.
• Для обновления конфигурации без перезапуска сервера — pnpm run config:reload.

---

Каталоги

• Исходники: src/
• Сборка: dist/
• Конфиг: .env.local
• Сертификаты: ssl/