Стартовый шаблон сборки фронтенда (версия 2.0)

Работоспособность сборки протестирована на node 16.14.2 и npm 8.5.0

Структура

• папка src - основная папка с исходниками.
• папка gulp - папка с задачами gulp и файлом config.js.
• файл gulpfile.babel.js - основной файл входа для описания задач таск-раннера GulpJS.
• файл .babelrc - файл-конфиг для работы связки gulp + babel.
• файл .editorconfig - файл-конфиг для редактора кода (все файлы внутри шаблона соответствуют этому конфигу).
• файл .gitignore - служит для указания в нём файлов и папок, которые необходимо скрыть от системы контроля версий git.
• файл package.json - стандартный файл с описанием, зависимостями шаблона а так же с ключом browserslist, в котором указана поддержка браузеров для работы некоторых плагинов.
• файл .prettierrc - файл-конфиг для работы плагина Prettier.
• файл README.md - файл с описанием структуры, нюансов работы и особенностями данного шаблона сборки фронтенда.

Начало работы

• Клонируем этот репозиторий.
• Устанавливаем зависимости командой npm i (ВАЖНО - инструмент сборки GulpJS должен быть установлен глобально).
• Запускаем команду gulp (если gulp и gulp-cli установлены глобально) или npm run start - запустится процесс сборки. Результат будет доступен в браузере по адресу http://localhost:3000/ (все доступные для просмотра адреса выводятся в консоль).

Принцип работы

• Все исходные файлы лежат в папке src.
• Результат работы сборщика отправляется в папку build.
• Есть два режима сборки - development и production.
• В файле gulp/config.js хранятся все основные пути, ключи и настройки.
• Для работы с файлами стилей используется препроцессор SASS и набор плагинов PostCSS.
• Для работы с файлами HTML используется шаблонизатор PUG.
• Для удобного отображения результата сборки, а так же "живой" перезагрузки браузера при изменениях, используется плагин browser-sync.
• Для работы с SVG-иконками используется набор плагинов, для создания из них одного файла-спрайта.

Подробней о файле config.js

• Все пути и настройки, используемые в задачах gulp, хранятся в этом файле.
• Ключ revision может быть установлен в значении true или false (по умолчанию) - включает, или отключает версионирование статических файлов CSS и JS в режиме сборки production.
• Ключ minifyHtml может быть установлен в значении true или false (по умолчанию) - включает, или отключает минификацию файлов HTML в режиме сборки production.
• Ключ splitOptions содержит настройки для работы PostCSS-плагина postcss-critical-split. Подробней о работе плагина ниже.

Описание основных задач

• gulp (или npm run start) - главная задача (режим сборки - development):
  • удаляет папку build и файл rev-manifest.json
  • собирает CSS, JS, HTML-файлы из исходников
  • собирает спрайт из SVG-иконок
  • копирует статические файлы
  • запускает локальный сервер
  • собирает результат своей работы в папку build
  • запускает вотчер за файлами, и перезапускает соответственные задачи при их изменениях
• gulp build (или npm run build) - задача сборки (режим сборки - production):
  • удаляет папку build и файл rev-manifest.json
  • собирает CSS, JS, HTML-файлы из исходников
  • минимизирует CSS, JS, HTML-файлы (в зависимости от настройки файла config.js)
  • встраивает стили из критического CSS инлайном в HTML
  • собирает спрайт из SVG-иконок
  • копирует статические файлы
  • собирает результат своей работы в папку build
• gulp build:dev - задача сборки (режим сборки - development):
  • удаляет папку build и файл rev-manifest.json
  • собирает CSS, JS, HTML-файлы из исходников
  • собирает спрайт из SVG-иконок
  • копирует статические файлы
  • собирает результат своей работы в папку build

Описание остальных задач

Сборка стилей

gulp sass - задача сборки файлов стилей. Нюансы:

• Исходные файлы стилей храним в папке src/sass.
• Для удобного написания респонсив медиа-запросов в сборку включен набор миксинов Include Media.
• В сборку включен базовый набор кастомных миксинов и функций (смотрите соответствующие файлы).
• В сборке используется обработка пост-процессором PostCSS. Описание плагинов, включенных в сборку:
  • postcss-normalize - добавляет части из normalize.css или sanitize.css, в зависимости от списка поддерживаемых браузеров (определенных в файле package.json)
  • postcss-viewport-height-correction - исправляет известную проблему, когда стиль 100vh не соответсвует реальной высоте экрана в мобильных браузерах (для корректной работы нужен скрипт, который включен в начало файла src/js/main.js)
  • lost - гибкая сетка, для подробной информации обратитесь к документации (пример использование есть в файле src/sass/global/_start-examples.scss)
  • postcss-animation - добавляет анимацию из библиотеки animate.css (пример использование есть в файле src/sass/global/_start-examples.scss)
  • postcss-magic-animations - добавляет анимацию из библиотеки Magic Animations (пример использование есть в файле src/sass/global/_start-examples.scss)
  • postcss-easings - заменяет имена временных функций анимаций с сайта easings.net на cubic-bezier()-функции
  • postcss-triangle - добавляет возможность удобного генерирование кода для создания CSS-треугольников (3 вида, пример использование есть в файле src/sass/global/_start-examples.scss)
  • postcss-will-change-transition - добавляет will-change в стили, в которых используется transition
  • postcss-will-change - добавляет backface-visibility: hidden; в стили, в которых используется will-change
  • postcss-flexbugs-fixes - пытается исправить известные баги с flexbox-свойствами
  • postcss-line-height-px-to-unitless - конвертирует значение свойства line-height, указанное в px, в относительное значение
  • postcss-pxtorem - конвертирует значения px в rem. По умолчанию затрагивает только свойства, связанные со шрифтами
  • postcss-momentum-scrolling - добавляет -webkit-overflow-scrolling: touch; в стили, в которых используется overflow: scroll;
  • postcss-aspect-ratio - добавляет возможность задать блоку размеры с соотношением сторон, используя так называемый "паддинг-хак" (пример использование есть в файле src/sass/global/_start-examples.scss)
  • postcss-color-mod-function - добавляет возможность смешивать цвета (пример использование есть в файле src/sass/global/_start-examples.scss)
  • postcss-rgb - добавляет возможность использовать rgb и rgba синтаксис вместе с hex-значениями (пример использование есть в файле src/sass/global/_start-examples.scss)
  • postcss-easing-gradients - добавляет возможность создавать красивые градиенты (пример использование есть в файле src/sass/global/_start-examples.scss, код градиента для плагина можно создать в редакторе)
  • postcss-border-align - добавляет возможность создавать внешние и внутренние границы, которые не влияют на лейаут (пример использование есть в файле src/sass/global/_start-examples.scss)
  • postcss-scrollbar - добавляет возможность легко настроить вид скроллбара (насколько эту возможность поддерживают браузеры, пример использование есть в файле src/sass/global/_start-examples.scss)
  • postcss-pseudo-class-enter - добавляет возможность использовать псевдо-класс :enter, получая на выходе :hover, :focus (пример использование есть в файле src/sass/global/_start-examples.scss)
  • css-declaration-sorter - сортирует свойства стилей. По умолчанию используется подход concentric-css
  • autoprefixer - добавляет вендорные префиксы. Плагин "смотрит" на список поддерживаемых браузеров в файле package.json, и добавляет только необходимые для этих браузеров префиксы
  • postcss-sort-media-queries - сортирует респонсив медиа-выражения, объединяя повторяющиеся в одно объявление. В опциях плагина нужно указать, какой подход к верстке используется - desktop-first или mobile-first (по умолчанию)
• В сборке реализовано разделение CSS на критический и остальной. Для объявления, какие именно свойства должны уйти в критический CSS, в исходных файлах используются управляющие комментарии /* critical:start */ и /* critical:end */ (пример использование есть в файле src/sass/global/_start-examples.scss). Поменять эти управляющие комментарии можно в файле config.js.
• В режиме сборки development, применяется минификация CSS при помощи плагина cssnano.
• В режиме сборки development, и установленном ключе revision в значение true, применяется версионирование CSS, при помощи добавление в имя файла хеш-суммы этого файла.

Сборка скриптов

gulp js - задача сборки файлов скриптов. Нюансы:

• По умолчанию используется два файла скриптов: bundle.js - для библиотек и main.js для собственных скриптов.
• Файл main.js проганяется через компилятор babeljs.
• Для работы с библиотеками, их подключение выполняется в файле gulp/tasks/js.js. Нужно прописать путь к библиотеке, предварительно установив их при помощи пакетного менеджера или положив файлы скриптов в папку src/js/libs. Пример такого подключения, а так же некоторые библиотеки включены в сборку (смотрите файл gulp/tasks/js.js, задачу js:bundle).
• В режиме сборки development, применяется минификация JS при помощи плагина gulp-uglify-es.
• В режиме сборки development, и установленном ключе revision в значение true, применяется версионирование JS, при помощи добавление в имя файла хеш-суммы этого файла.

Сборка HTML

gulp pug - задача сборки файлов HTML. Нюансы:

• В сборке используется применение шаблонизатора PUG. Для ознакомления с принципами разработки при помощи данного инструмента, обратитесь к документации а так же, изучите базовую структуру, представленную в данном шаблоне в папке src/pug.
• В режиме сборки development, критические стили из файлов CSS вставляется инлайном в файлы HTML (для этого в строчке подключения таких стилей в PUG надо дополнительно прописать атрибут data-inline-critical - пример в файле src/pug/layouts/_css-critical.pug).
• В режиме сборки development, и установленном ключе minifyHtml в значение true, применяется минификация файлов HTML.
• В сборке учтены все нюансы по автоматической замене путей к файлам CSS и JS после их переименований (если такие произошли в процессе сборки).
• Итоговые файлы HTML можно прогнать через валидатор командой npm run validate; в случае невалидного HTML ошибки выводятся в консоль.

Сборка SVG-спрайта

gulp sprite - задача сборки SVG-иконок а один файл спрайта. Нюансы:

• Сборка предусматривает возможность генерации двух вариантов спрайта: моно и мульти-цветный.
• SVG-иконки для моно-цветного спрайта должны быть предварительно подготовлены, а именно:
  • иконки должны быть разобраны
  • иконки должны быть моноцветными (содержать только один цвет заливки)
  • рекомендуется проводить ручную оптимизацию при помощи инструмента SVGOMG
• SVG-иконки для мульти-цветного спрайта не должны быть сложными, не долждны содержать в себе внутренних ссылок на эффекты (например на градиенты), и предварительно оптимизированы.
• Готовые спрайты с иконками после сборки будут находиться в папке build/img/sprites.
• Подключение иконок выполняется при помощи миксина в PUG - пример моноцветной иконки: +icon-mono('icon-telegram', 'Telegram icon'), где icon-telegram - название иконки, и одновременно ее класс, а второй (необязательный) атрибут Telegram icon - это aria-label для этой иконки.
• Для подключения мульти-цветной иконки используется похожий миксин - пример: +icon-multi('icon-js', 'JavaScript icon').
• Размеры подключенным иконкам можно задавать в CSS при помощи свойства font-size (размер будет высчитан по высоте).
• Цвет подключенным иконкам можно задавать в CSS при помощи свойства color (только для моно-цветных иконок).
• Для корректного отображения SVG-спрайтов в браузере IE11 нужно подключить JS-полифил svg4everybody (подключен по умолчанию).

Копирование статических файлов

gulp copy - копирует изображения, видео, фавиконки, шрифты, вендорные JS-библиотеки. При необходимости - можно расширить функционал по аналогии (смотрите файл gulp/tasks/copy.js).

Очистка рабочих фалов

gulp clean - удаляет папки и файлы, созданные в процессе сборки.

---

В случае обнаружений проблем/багов/недочетов - отправляйте пулл-реквесты с исправлениями

---

Лицензия - MIT: ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ, СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И ОТСУТСТВИЯ НАРУШЕНИЙ, НО НЕ ОГРАНИЧИВАЯСЬ ИМИ. НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ИСКАМ, ЗА УЩЕРБ ИЛИ ПО ИНЫМ ТРЕБОВАНИЯМ, В ТОМ ЧИСЛЕ, ПРИ ДЕЙСТВИИ КОНТРАКТА, ДЕЛИКТЕ ИЛИ ИНОЙ СИТУАЦИИ, ВОЗНИКШИМ ИЗ-ЗА ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ ДЕЙСТВИЙ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.