Мой стартовый репозиторий

В моей практике по-прежнему встречаются проекты, требующие на выходе самый обычный набор html, css, js, картинок и прочих доп. файлов, поэтому недавно я обновил свой стартовый репозиторий для таких проектов аж до 4-й версии. Главное нововведение 4-й версии: автоматика самостоятельно определяет используемые блоки и берёт их в сборку.

Что это такое

Это репозиторий на github, с клонирования которого я начинаю каждый проект по вёрстке. Внутри методология БЭМ, pug и SCSS. Автоматизация сделана с gulp и webpack.

Собственно, это простая система сборки проекта, для которого хочется компонентного подхода, но без js-фреймворков.

Порог вхождения низкий: установленный Node.js, базовый навык работы с терминалом.

Зачем

Привычное работающее окружение. Приятно начинать проект с набором хорошо знакомых инструментов.

Разделение на блоки. Как в полном стеке БЭМ-а: все файлы блока хранятся в папке блока. К примеру, папка src/blocks/main-nav содержит все файлы, нужные для работы главной навигации: файл с пунктами меню, pug-примеси с разметкой, стили, javascript.

В сборку автоматически попадут только используемые блоки. Если БЭМ-блок упомянут в разметке страницы или указан в секции alwaysAddBlocks файла config.js, то его разметочный, стилевой и скриптовой файлы попадут в сборку (если существуют). Если блок перестаёт использоваться в разметке страниц, из сборки автоматически пропадает всё, что его касается.

Библиотека готовых компонентов с минимальной стилизацией. Один раз написал разметку и базовые стили повторяющихся элементов (кнопки, поля форм, главная навигация, «шапка», «подвал» и т.п.) и использую их, добавляя нужные проекту стили. Библиотека блоков имеет веб-представление, служащее её документацией.

Команда быстрого создания файловой структуры блока. node createBlock.js new-block pug js — создаст src/blocks/new-block, две пустые подпапки для изображений, scss-, pug- и js-файлы со стартовым содержимым. Если не указать в конце команды доп. расширения pug и js, соответствующие файлы не будут созданы.

Нет css-reset и normalize. Используется что-то вроде бутстраповского reboot — блок page (этот класс написан на теге html), включающего стили «прибитого подвала».

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

Описание работы есть в репозитории. На момент написания этого текста после запуска сервера разработки (npm start) происходит следующее:

1. Очищается папка сборки (build/).
2. Записывается файл src/pug/mixins.pug с include pug-файлов всех блоков.
3. Файлы страниц (src/pages/**/*.pug) компилируются в html.
4. Из скомпилированных html-файлов извлекается список всех классов уровня БЭМ-блока. На основании этого списка будут построены диспетчер подключения стилей и список всех js-файлов проекта.
5. Генерируются спрайты, в папку сборки копируются картинки блоков и доп. файлы из секции addAssets файла config.js.
6. Записывается диспетчер подключения стилей src/scss/style.scss, в котором:
   • Импорты файлов из секции addStyleBefore файла config.js. По умолчанию — SCSS-переменные и примеси.
   • Импорты файлов БЭМ-блоков, использующихся на проекте.
   • Импорты файлов БЭМ-блоков, упомянутых в секции alwaysAddBlocks файла config.js (таким образом можно взять в сборку любой блок, даже если его css-класс не упоминается в разметке).
   • Импорты файлов из секции addStyleAfter файла config.js. По умолчанию — стили для печати страницы.
7. Записывается диспетчер подключений скриптов src/js/entry.js, в котором:
   • require файлов из секции addJsBefore файла config.js.
   • require файлов БЭМ-блоков, использующихся на проекте.
   • require файлов БЭМ-блоков, упомянутых в секции alwaysAddBlocks файла config.js.
   • require файлов из секции addJsAfter файла config.js.
8. Компилируются и обрабатываются PostCSS-плагинами стили (src/scss/style.scss).
9. Javascript (src/js/entry.js) собирается webpack-ом.
10. Запускается локальный сервер и слежение за файлами.

При изменениях в разметке, стилях и скриптах происходит пересборка и автообновление страницы в браузере (в случае стилей — без перезагрузки страницы).

Как я с этим работаю

Клонирую репозиторий, захожу в папку проекта, удаляю папку .git, инициирую новый репозиторий, привязываю удалённый репозиторий, устанавливаю зависимости.

Запускаю сервер разработки (для команды npm start у меня есть алиас s).

Редактирую шаблон(ы) страниц (src/pug), если нужно. Сколько на проекте типов раскладок блоков по странице, столько (обычно) бывает и pug-шаблонов.

Пишу разметку страниц, используя готовые pug-примеси из библиотеки и добавляя нужные проекту блоки командой node createBlock.js ИМЯБЛОКА (при этом можно не останавливать сервер).

Для неповторяющихся (в отрисованном дизайне) структурных блоков не создаю pug-примесей, пишу их разметку напрямую в файлах страниц. Но для повторяющихся блоков я сразу добавляю pug-файл с примесью и описанием API этой примеси (см. пример).

Определяю SCSS-переменные, стилизую базовую типографику, стилизую блоки библиотеки до проектного вида. Параллельно стилизую специфические блоки проекта.

Если нужно взять в сборку блоки, классы которых не упоминаются в разметке (скажем, sprite-png, собирающий растровый спрайт), останавливаю сервер и перечисляю нужные блоки в секции alwaysAddBlocks файла config.js. Если нужны какие-либо дополнительные файлы (шрифты, фавиконки…), перечисляю их и путь их копирования в том же config.js.

Лицензия, поддержка

Лицензия свободная, можно использовать как весь проект, так и его части в коммерческих целях.

Поставляется «как есть», все риски — ваши. Поддержка и сообщения о багах — в ишью репозитория.

Заключение

На мой взгляд, у каждого, кто занимается вёрсткой, должен быть стартовый репозиторий для подобных проектов (не обязательно свой).