multijump / staking-ui

Front-end/Вёрстка сайта. Gulp сборщик. Pug + Sass/SCSS.

Спасибо что выбрали работу с нашей командой!
Данным описанием мы постараемся донести всю необходимую информацию по работе с нашей вёрсткой. Расскажем о существующей структуре, как с ней работать, как без труда скомпилировать самостоятельно.

Сборщик необходим для автоматизации задач в повседневной front-end разработке. Стили компилируются из Sass/SCSS, HTML код из Pug. Данные препроцессоры позволяют существенно ускорить разработку, а также упростить дальнейшую поддержку. Автоматически сжимаются файлы, оптимизируются картинки, JS код можно писать на последнем ECMAScript. При каждом сохранении файла в редакторе, браузер автоматически перезагружает страницу.

Общая структура

• html — собранная, оптимизированная и полностью готовая к использованию вёрстка;
• sources — исходные файлы проекта, сам сборщик, конфиги и прочее;
• README.md — данный readme.

Скорее всего вам потребуется только содержимое html. Однако мы рекомендуем организовать работу таким образом, чтобы вручную ничего не вносилось, не правилось в данной папке. Т.к. в случае дальнейших доработок с нашей стороны, вам может потребоваться повторно делать все изменения в собранной вёрстке либо вручную переносить обновления в свой код. Постарайтесь автоматизировать процесс, либо документировать все необходимые изменения, чтобы при получении обновлённой html вы могли без труда обновить код у себя.

Приветствуется работа с sources. После изменений вы можете передать её обратно и мы спокойно продолжим работу. Обмен также удобно организовать через Git.

Как работать с исходниками?

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

Что включает в себя сборка?

• browser-sync - живая перезагрузка веб-страницы при внесении изменений в файлы вашего проекта;
• gulp-autoprefixer — автоматически расставляет префиксы в CSS в соответствии с сервисом Can I Use;
• gulp-babel - использование ECMAScript с Babel;
• gulp-uglify — минификация JS-файлов;
• gulp-pug — компиляция Pug в HTML;
• gulp-sass — компиляция Sass/SCSS в CSS;
• gulp-clean-css — минификация CSS-файлов;
• gulp-sourcemaps - карта стилей;
• gulp-concat - объединение файлов;
• gulp-add-src — добавление файлов для объединения;
• gulp-imagemin — сжатие изображений PNG, JPG, GIF и SVG;
• imagemin-pngquant — дополнение к gulp-imagemin для работы с PNG-изображениями;
• imagemin-jpeg-recompress — дополнение к gulp-imagemin для работы с JPG-изображениями;
• gulp-webp — создание и оптимизация изображений в формате WebP;
• gulp-favicons — генератор фавиконок для вашего проекта;
• gulp-svg-sprite — создание SVG-спрайтов;
• gulp-replace - замена строк в исходных файлах;
• gulp-newer — дополнительный плагин к gulp-imagemin, позволяет сжимать только новые изображения;
• gulp-plumber — оповещения в командной строке (например, ошибки в Sass/SCSS);
• gulp-debug — отладка в терминале;
• gulp-watch — отслеживание изменений в ваших файлах проекта;
• gulp-clean — удаление файлов и папок.

Как подготовиться?

• Node версии 12+ должен быть установлен;
• Yarn версии 1.22+ должен быть установлен;

дополнительно для Windows может понадобиться...

• Git for Windows;
• в PowerShell, запущенной от имени адмиинистратора:

npm install --global windows-build-tools

Set-ExecutionPolicy -ExecutionPolicy Unrestricted

дополнительно для Linux может понадобиться...

• на примере Ubuntu 18.04+:

sudo apt install -y build-essential attr autoconf libjpeg-dev libpng-dev libtiff-dev libgif-dev

• скачайте вёрстку как zip и распакуйте или клонируйте с гита (возможно, вы уже сделали это, если читаете данный документ);
• перейдите в консоли в папку с исходниками:

cd sources

• введите команду, которая скачает необходимые компоненты для корректной работы сборщика:

yarn

По завершению должно быть сообщение вида:

➤ YN0000: └ Completed in XXs
➤ YN0000: Done in XXm

или

➤ YN0000: └ Completed in XXs
➤ YN0000: Done with warnings in XXm

Если процесс завершился с ошибкой, пожалуйста, убедитесь, что все вышеуказанные компоненты установлены и их версии соответствуют. Если проблему не удаётся решить — свяжитесь с нами, подскажем как действовать.

Как собрать?

Как вы уже знаете, проект собирается в папку html рядом с sources.

У нас открыт терминал, рабочая директория — sources
Запускаем:

yarn run gulp

У вас должен открыться браузер с локальным сервером и работающим browser-sync. Сборка прошла успешно, вёрстка в папке html полностью обновлена из текущих исходников.

Одновременно запущен мониторинг на следующие директории:

• sources/src/pug/**/*.pug
• sources/src/sass/**/*.{scss,sass}
• sources/src/fonts/**/*
• sources/src/images/**/* — все картинки проходят автоматическое сжатие
• sources/src/images/favicons/* — из одной картинки генерируется необходимый набор фавиконок
• sources/src/images/skip-optimization/**/* — здесь картинки минуют оптимизацию
• sources/src/images/sprite-svg/*.svg — здесь svg собираются в один спрайт
• sources/src/js/**/*.js — из js файлов собирается один main.min.js
• sources/src/html_direct_copying/**/* — статичные файлы/папки, копируются прямиком в html

Для останавки мониторинга и локального сервера нажмите Ctrl + C в терминале.

Команды (таски) сборщика

Зачастую, для готового проекта требуется изменение только отдельных элементов (стилей, изображений, скриптов, html), не запуская сборку целиком по новой. В сборщике доступны следующие команды обновления:
yarn run gulp pug — html кода
yarn run gulp styles — стилей
yarn run gulp styles_unmin — стили будут без минификации
yarn run gulp scripts — скриптов
yarn run gulp scripts_unmin — скрипты без минификации*
yarn run gulp favicons — favicon
yarn run gulp images — изображений
yarn run gulp sprite — svg-спрайтов (после чего обязательно обновление стилей, см.выше)
yarn run gulp html_direct_copying — прямое копирование всего из sources/src/html_direct_copying в папку html

Копирование вновь добавленных библиотек:
yarn run gulp libs (после чего обязательно обновление скриптов, см.выше)

Команды сборки всего проекта, но без запуска мониторинга:
yarn run gulp build
yarn run gulp build_unmin — сборка без минификации*

Запуск только мониторинга:
yarn run gulp watch
yarn run gulp watch_unmin — без минификации*

* — обратите внимание на необходимость подключения js библиотек по отдельности в sources/src/pug/base/_layout.pug.

Sass vs SCSS

Сборщик поддерживает оба формата. Единственное условие — один .sass или .scss файл должен быть написан либо на чистом sass синтаксисе, либо scss. При этом разные файлы, которые вы имортируете, могут быть по разному и написаны (.sass или .scss соответственно).

Оптимизация изображений

Сборщик проводит автоматическое сжатие изображений, приоритет отдан максимальному визуальному качеству, без явных артефактов на любых дисплеях. Учитывая это, Google PageSpeed или другие аналогичные инструменты анализа сжатия изображений, могут сообщать о необходимости ещё сжать изображения — решать вам, что важнее. Изменить степень сжатия можно соответствующими параметрами в sources/gulp/tasks/images.js и перезапустить сборку gulp.

JPG: оптимизация настроена и отлично работает, главное — использовать JPG с качеством 100% (без какого-либо первоначального сжатия).

PNG: оптимизация настроена и работает хорошо. В некоторых случаях TinyPNG будет лучше (по качеству и/или степени сжатия), но в целом результат близкий. PNG также сохранять оригинальный (PNG24), без сжатия и/или каких-либо оптимизаций.

SVG: оптимизация настроена и работает отлично. Однако сам по себе формат svg очень сложный, он может включать внутри в том числе и растровую графику(!), анимации, поэтому не исключена потеря/искажение svg на выходе (в таком случае воспользуйтесь советом ниже). Тем не менее, при тестировании, каких-либо проблем с данным оптимизатором не выявлено.

В сборке присутствует папка sources/src/images/skip-optimization/ — все файлы из неё копируются без какого-либо вмешательства сразу в html/images/. Сделано на случай, если вдруг какой-то из оптимизаторов сработал плохо для того или иного изображения (оптимизируем вручную в таком случае). Внимание: сохраняя файл в sources/src/images/skip-optimization/ убедитесь, что нет файла с таким же именем в основной папке sources/src/images/.

Изображения в формате WebP

В сборщик встроена возможность автоматического создания и оптимизации формата WebP. Для этого используем папку sources/src/images/webp/ — все изображения (любого формата) из неё автоматически конвертируются с оптимизацией в формат WebP и сохраняются в основной поток html/images/. Качество конвертации — 85. Достаточно для большинства случаев, но если нужен меньший вес или, наоборот, лучшее качество, то данный параметр можно изменить в sources/gulp/tasks/images.js и перезапустить gulp.

Одни и те же изображения, с теми же именами, можно одновременно сохранять в sources/src/images/webp/ и в sources/src/images/. На выходе все будут в одной папке, но со своими расширениями.

Иконочный шрифт? Больше не используем!

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

Bower или подключение плагинов (в том числе таких как jQuery, slick и др.)

Раньше для автоматического скачивания библиотек, плагинов был популярен Bower, сейчас практически все поддерживают добавление через NPM или Yarn.

Например, вам нужен jQuery (вероятно, уже используется в вёрстке), вводим команду: yarn add jquery.

Либа скачается в "недра" .yarn, а также будет прописана зависимость в sources/package.json, секция dependencies. Когда зависимость уже прописана — данные команды не нужны, все автоматически скачается при развертывании проекта (yarn). Для удаления: yarn remove jquery. Также можно вручную почистить sources/package.json и запустить yarn. Примечание: удаленные таким образом либы автоматически не удаляются из sources/src/libs. Всё лишнее чистим там вручную.

Далее запускаем: yarn run gulp libs (или полную сборку снова yarn run gulp) — либы целиком скопируются в sources/src/libs. Там будут в том числе исходные файлы, документация. В вёрстке обычно используются только собранные минифицированные дистрибутивы, чаще всего они в папке dist.

Путь к библиотекам прописывается в sources/src/js/_libs_concat.js. При сборке все JS сливаются в один файл html/js/main.js он и подключен в pug sources/src/pug/base/_layout.pug.

Вопросы, замечания, предложения?

Пишите нам!