Gulp сборка для фронтенд-разработки

используеться Gulp 5 версии

---

Установка

1. Скачайте и установите Node.js версии 18.20.5 или выше.
2. Создайте новый проект.
3. Клонируйте репозиторий (git clone <this repo>) или скачайте архив и распакуйте его вручную.
4. В корне проекта выполните команду npm i для установки зависимостей.

Использование

• gulp — запустить проект в режиме разработчика.
• gulp --build — собрать сборку в режиме production.
• gulp --prev — просмотреть результаты в режиме production.
• gulp zip — создать zip-файл проекта.
• gulp ghpages — создаст вам github pages. Более докладно тут

Структура файлов

.
├─ app                			# Главная папка для работы
│  ├── blocks         			# HTML файлы
│  ├── fonts          			# Шрифты
│  ├── images         			# Изображения
│  │   └── sprite     			# SVG-файлы для спрайтов
│  ├── js             			# Скрипты
│  │   ├── components 			# JS-компоненты
│  │   └── libs       			# Библиотеки
│	 ├── pug
│	 │ 	 ├── components	  		# Pug-компоненты
│	 │ 	 └── pages        		# Страницы 
│  ├── resources      			# Разные файлы (PHP, favicon, видео)
│  └── scss          				# Стили
│      ├── base      				# Базовые стили
│      ├── components 			# SCSS-компоненты
│      ├── libs      				# Библиотеки
│      └── mixins    				# Миксины
│
├── .editorconfig     			# Настройки форматирования кода
├── .eslintrc.json    			# Настройки ESLint
├── .htmlhintrc       			# Настройки HTMLHint
├── .pug-lintrc.json				# Линтер для Pug
├── .stylelintrc.json 			# Настройки Stylelint
├── gulpfile.js       			# Конфигурация Gulp
├── package.json      			# Настройки и зависимости проекта
├── readme.txt        			# Документация сборки(сокращенный вид)
└── README.md         			# Документация сборки

Навигация

1. HTML
2. PUG
3. CSS
4. JS
5. SVG
6. Инные ресурсы
7. Изображения
8. Шрифты
9. Возможности
10. Github Pages
11. Local Tunnel
12. Изменения

HTML

• Проверка html на БЭМ методологию.

• Благодаря плагину gulp-file-include можно разделять на html-файлы, которые хранятся в папке blocks

  Для вставки html-частей в главный файл используйте @include('./blocks/filename.html')

  В других html файлах так же можно использовать include, просто замените путь на правильный

• При режиме production вы получите сжатый(минифцированный) и очищенный от комментариев html-код. Если вам не нужен минифцированный код, вы можете в gulpfile.js найти функцию html и там раскомментировать нужный блок кода

• Используется htmlhint для проверки корректности написания html-кода

• Используется валидация w3c для соответствия html-кода стандартам

PUG

• Возможность работать с препроцессором pug. Все исходные файлы должны располагаться исключительно в папке pug иначе компиляция в хтмл код не будет происходить
• Для использования Pug необходимо в файле config.json присвоить markupType значение pug
• Используется gulp-pug-linter, для правильного написания кода
• В режиме production вы получите сжатый(минифицированный) код. Чтобы получить код без минификации следуйте указаниям, в функции pug в файле gulpfile.js

CSS

• В сборке используеться scss препроцессор
• Все файлы с папки scss подключать в файл main.scss
• Для подключения файлов используйте директиву @use, @forward
• Если нужно подключить сторонние css-файлы (библиотеки) — положите их в папку libs. Затем так же подключите в main.scss
• В режиме production вы получите сжатый(минифцированный) и очищенный от коментариев css-код
• Используеться stylelint для правильного порядка записи свойств. Чтобы stylelint начал работать в settings.json нужно прописать такое свойство "stylelint.validate": ["css", "less", "postcss", "scss"]. Так же скачать плагин stylelint

JavaScript

• В сборке используеться webpack
• Js код можно разделить на отдельные файлы, расположенные в папке components. Подключение файлов осуществляется с помощью импорта ES6 модулей.
• Если нужно подключить сторонние библиотеки — положите их в папку libs. Затем так же подключите в main.js. По умолчанию уже есть некоторые.
• Проверка js кода на наличие ошибок с помощью Eslint. Для того чтобы Eslint работал, скачайте плагин ESLint и в settings.json пропишите

   "eslint.enable": true,
   "eslint.codeActionsOnSave.mode": "problems",

Изображения

• Все изображения, кроме ico, необходимо поместить в папку images.
• В режиме production изображения будут сжаты и конвертированы в форматы avif и webp. Подключить их можно с помощью тега picture (который) автоматически подключиться вместо тегов img, если будет расширение svg, то не будет конвертирован в тег picture

SVG

• Если вам не нужны SVG-спрайты, просто помещайте файлы в папку images или в другие созданные вами папки (кроме sprite). Если же спрайты необходимы, разместите их в папке sprite. Такие атрибуты как fill, stroke, style будут автоматически удаляться при svg-спрайтах

Инные ресурсы

• Для других ресурсов таких как

  php, video, ico, webp, avif и прочие положите их в папку resources.

Шрифты

• В папку fonts помещайте шрифты в любом формате, кроме woff, так как они не будут конвертированы. Файлы шрифтов должны иметь названия с тире, например: "Roboto-Medium" или "Roboto-BlackItalic", чтобы автоподключение работало корректно.
• Файл _fonts.scss в папке scss будет создан автоматически при подключении шрифтов. Если вы добавили новый шрифт, его нужно подключить вручную в этом файле с помощью include. Либо вы можете удалить этот файл и перезапустить сборку — в этом случае шрифты подключатся автоматически.

Возможности

• Для корректного отображения текста на странице был подключен плагин типограф, которые автоматически добавит неразрывные пробелы и иные символы, чтобы текст везде отображался по всем правилам
• Чтобы упростить написание путей в VS Code, можно настроить плагин Path Autocomplete(скачав его). Добавьте в файл настроек JSON следующий код:

"path-autocomplete.pathMappings": {
  "#img": "${folder}/app/images"
}

Теперь, используя #img, вы сможете автоматически получать подсказки для путей к изображениям. Например: #img/icon/arrow.svg

Github Pages

В версии 1.0.3 добавлена добавлена возможность автоматически создать Github Pages из вашего проекта(по сути, бесплатный хост для вашего сайта) Чтобы разместить проект - нужно:

1. Открыть консоль git в папке с вашим проектом
2. Создать пустой репозиторий на Github
3. Зайти обратно в консоль и прописать следующие команды по очереди

git init
git add .
git commit -m 'upload'
git branch -M main
git remote add origin https://github.com/{Ваш username}/{Название репозитория который вы создали}.git
git push -u origin main

git commit -m 'upload' - название коммита может быть любым

git remote add origin https://github.com/{Ваш username}/{Название репозитория который вы создали}.git - замените {Ваш_пользователь} и {Название_репозитория} на нужные значения из вашего репозитория. Ссылку можно взять в репозитории или 4. После того, как ваш проект будет загружен, пропишите в консоли npm run deploy. Эта команда создаст ветку gh-pages и автоматически запустит. Чтобы скопировать эту ссылку, нужно перейти в ваш репозиторий. Потом settings ⇒ pages и там вы найдете ссылку. Пример https://<username>.github.io/<repo-name>/. Не забудьте дописать эту ссылку на ваш хтмл файл https://<username>.github.io/<repo-name>/index.html 5. Для вашей кастомной настройке вы можете перейти в gulpfile.js, найти функцию ghpages и настроить все под себя. Чтобы вызвать эту функцию, пропишите в консоль gulp ghpages

Local Tunnel

С версии 1.0.5 добавлена возможность автоматически создать сервер, который доступен каждому пользователю. Чтобы сервер включялся автоматически в config.json поставить enabled на true

---

Изменения

версия 1.0.2 (22.12.2024)

1. Изменил зависимости на более новые версии (теперь node js нужен версии 18.20.5 и выше)
2. Добавлен плагин w3c-html-validator, который автоматически проверяет ваш html код на валидность и выводить ошибки в консоль
3. Теперь возможен импорт css-файлов в js-файлы (ранее импортировались только js-файлы). Пример import 'simplebar/dist/simplebar.css'
4. В dependencies добавлены новые библиотеки в том числе и мой плагин darkmodal для модальных окон, который уже подключен в app/js/libs/modal.js. Для завершения настройки его нужно подключить main.js. Для получения подробной информации о использовании → ссылочка
5. Добавлены и улучшены различные функции и миксины в scss. Теперь необходимо в app/scss/base/_vars.scss указать максимальную ширину и минимальную ширину сайта. Так же переходим на rem еденицы измерения для лучшей доступности (в процессе)

версия 1.0.3 (03.01.2025)

1. Добавлена поддержка компиляции pug файлов в хтмл.
2. Теперь вы сами можете выбрать html файлы или pug. Просто установите нужное значение в начале gulpfile.js. По умолчанию html
3. Автоматическая загрузка вашего проекта на Github Pages
4. Обновлен конфигурационный файл eslintrc.json
5. Полный переход на использование единиц измерения rem для улучшения доступности
6. Оптимизированы и удалены миксины
7. Добавлен файл для линтера pug файлов

версия 1.0.4 (23.02.2025)

1. Сделан config.json в котором будут лежать основыне настройки проекта
2. Добавлен Ngrok для создания сервера, который доступен каждому пользователю
3. Добавлены и улучшены миксины

версия 1.0.5 (15.03.2025)

1. Ngrok был заменен на Local Tunnel по одной простой причине: в Ngrok действовали ограничения на количество запросов, и чтобы их снять, требовалась оплата
2. Небольшие улучшения

---

Заключение

Если вы нашли баг, ошибку, недоработку или просто дать идеи для сборки — пишите мне в 💬 Telegram!