KoBa4 / gulp-maxgraph

My gulp settings

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Gulp - сборка MaxGraph

Используется Gulp 4

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

Для работы с данной сборкой в новом проекте, склонируйте все содержимое репозитория
git clone <this repo> Затем, находясь в корне проекта, запустите команду npm i, которая установит все находящиеся в package.json зависимости. После этого вы можете использовать любую из предложенных команд сборки (итоговые файлы попадают в папку app корневой директории):
gulp - базовая команда, которая запускает сборку для разработки, используя browser-sync

gulp build - команда для продакшн-сборки проекта. Все ассеты сжаты и оптимизированы для выкладки на хостинг.

gulp cache - команда, которую стоит запускать после gulp build, если вам нужно загрузить новые файлы на хостинг без кэширования.

gulp backend - команда для бэкенд-сборки проекта. Она лишена ненужных вещей из dev-сборки, но не сжата, для удобства бэкендера.

gulp zip - команда собирает ваш готовый код в zip-архив.

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

├── gulpfile.babel.js/            # Папка с настройками Gulp
│   ├── config                    # Настройки Gulp
│   │   └── paths.js              # Пути к папкам и файлам
│   ├── tasks                     # Задачи Gulp
│   │   ├── cache-task.js         # Задача для кэширования файлов
│   │   ├── clean.js              # Задача для очистки папки сборки
│   │   ├── html-include.js       # Задача для сборки HTML
│   │   ├── images.js             # Задача для обработки изображений
│   │   ├── index.js              # Входной файл задач
│   │   ├── resources.js          # Задача для копирования ресурсов
│   │   ├── rewrite.js            # Задача для перезаписи ссылок на ассеты
│   │   ├── scripts.js            # Задача для обработки JS
│   │   ├── scripts-backend.js    # Задача для обработки JS для бэкенда
│   │   ├── styles.js             # Задача для обработки CSS
│   │   ├── styles-backend.js     # Задача для обработки CSS для бэкенда
│   │   ├── svg-sprites.js        # Задача для сборки SVG спрайтов
│   │   └── zip.js                # Задача для сборки в zip-архив
│   └── index.js                  # Главный файл Gulp
├── src/                          # Исходники
│   ├── js                        # Скрипты
│   │   └── main.js               # Главный скрипт
│   │   ├── _vars.js              # файл с переменными проекта
│   │   ├── _vendor.js            # файл с подключениями библиотек
│   │   ├── _components.js        # файл с готовыми функциями на js
│   │   ├── _components.js        # файл с подключениями компонентов
│   │   ├── components            # js-компоненты
│   │   ├── vendor                # папка для загрузки локальных версий библиотек
│   ├── scss                      # Стили сайта (препроцессор sass в scss-синтаксисе)
│   │   └── main.scss             # Главный файл стилей
│   │   └── vendor.scss           # Файл для подключения стилей библиотек из папки vendor
│   │   └── _fonts.scss           # Файл для подключения шрифтов (можно использовать миксин)
│   │   └── _mixins.scss          # Файл для подключения миксинов из папки mixins
│   │   └── _vars.scss            # Файл для написания css- или scss-переменных
│   │   └── _settings.scss        # Файл для написания глобальных стилей
│   │   ├── components            # scss-компоненты
│   │   ├── mixins                # папка для сохранения готовых scss-компонентов
│   │   ├── vendor                # папка для хранения локальных css-стилей библиотек
│   ├── partials                  # папка для хранения html-частей страницы
│   ├── img                       # папка для хранения картинок
│   │   ├── svg                   # специальная папка для преобразования svg в спрайт
│   ├── resources                 # папка для хранения иных ассетов - php, видео-файлы, favicon и т.д.
│   │   ├── fonts                 # папка для хранения шрифтов в формате woff2
│   └── index.html                # Главный html-файл
└── package.json                  # файл с настройками сборки и установленными пакетами
└── .editorconfig                 # файл с настройками форматирования кода
└── .ecrc                         # файл с настройками пакета editorconfig-checker (исключает ненужные папки)
└── .stylelintrc                  # файл с настройками stylelint
└── README.md                     # документация сборки

Оглавление

  1. npm-скрипты
  2. Работа с html
  3. Работа с CSS
  4. Работа с JavaScript
  5. Работа со шрифтами
  6. Работа с изображениями
  7. Работа с иными ресурсами
  8. Типограф
  9. Рекомендуемые плагины VS Code
  10. Локальные сниппеты
  11. Готовые модули
  12. Заключение

npm-скрипты

Вы можете вызывать gulp-скрипты через npm. Также в сборке есть возможность проверять код на соответствие конфигу (editorconfig) и валидировать html.

npm run html - запускает валидатор html, запускать нужно при наличии html-файлов в папке app.

npm run code - запускает editorconfig-checker для проверки соответствия конфиг-файлу.

Работа с html

Благодаря плагину gulp-file-include вы можете разделять html-файл на различные шаблоны, которые должны храниться в папке partials. Удобно делить html-страницу на секции.

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

Если вы хотите создать многостраничный сайт - копируйте index.html, переименовывайте как вам нужно, и используйте.

При использовании команды gulp build, вы получите минифицированный html-код в одну строку для всех html-файлов.

Работа с CSS

В сборке используется препроцессор sass в синтаксисе scss.

Стили, написанные в components, следует подключать в main.scss. ВАЖНО: Обязательно удалить стили, которые написаны в main.scss для .page__body.

Чтобы подключить сторонние css-файлы (библиотеки) - положите их в папку vendor и подключите в файле _vendor.scss

Если вы хотите создать свой миксин - делайте это в папке mixins, а затем подключайте в файл _mixins.scss.

Если вы хотите использовать scss-переменные - подключите _vars.scss также в main.scss или в любое другое место, где он нужен, но обязательно удалите :root.

Для подключения css-файлов используйте директиву @import

В итоговой папке app/css создаются два файла:
main.css - для стилей страницы,
vendor.css - для стилей всех библиотек, использующихся в проекте.

При использовании команды gulp build, вы получите минифицированный css-код в одну строку для всех css-файлов.

Работа с JavaScript

Для сборки JS-кода используется webpack.

JS-код лучше делить на компоненты - небольшие js-файлы, которые содержат свою, изолированную друг от друга реализацию. Такие файлы помещайте в папку components, а потом импортируйте в файл _components.js

В файле vars.js должны храниться базовые переменные проекта, вроде нахождения элементов и т.д.

В файле main.js ничего менять не нужно, он сделан просто как результирующий.

Подключать сторонние библиотеки можно через npm, для этого существует файл _vendor.js. Импортируйте туда подключения.

Если какой-то библиотеки нет в npm или просто нужно подключить что-либо локальным файлом - кладите его в папку vendor и точно так же импортируйте, но уже с путем до файла.

При использовании команды gulp build, вы получите минифицированный js-код в одну строку для всех js-файлов.

Работа со шрифтами

Т.к. автор не поддерживает IE11, в сборке реализована поддержка только формата woff2 (это значит, что в миксине подключения шрифтов используется только данный формат).

Загружайте файлы woff2 в папку resources/fonts, а затем вызывайте миксин @font-face в файле _fonts.scss.

Также не забудьте прописать эти же шрифты в <link preload> в html.

Работа с изображениями

Любые изображения, кроме favicon кладите в папку img.

Если вам нужно сделать svg-спрайт, кладите нужные для спрайта svg-файлы в папку img/svg. При этом, такие атрибуты как fill, stroke, style будут автоматически удаляться. Иные svg-файлы просто оставляйте в папке img.

При использовании команды gulp build, вы получите минифицированные изображения в итоговой папке img.

В сборке доступна поддержка webp и avif форматов. Подключить их вы можете через тег picture. Для background можно использовать обычные jpg или png, либо использовать image-set там, где это возможно.

Работа с иными ресурсами

Любые ресурсы (ассеты) проекта, под которые не отведена соответствующая папка, должны храниться в папке resources. Это могут быть видео-файлы, php-файлы (как, например, файл отправки формы), favicon и прочие.

Типограф

Для корректного отображения текста на странице был подключен плагин типограф, которые автоматически добавит неразрывные пробелы и иные символы, чтобы текст везде отображался по всем правилам русского языка.

Рекомендуемые плагины для VS Code

Я рекомендую использовать именно VS Code, и в сборке реализовано взаимодействие именно с этим редактором. Так, при открытии папки со сборкой в VS Code, редактор предложит вам ранее не установленные плагины, которые подойдут для корректной работы сборки.

Самый важный из них – projects snippets, этот плагин "включает" локально написанные сниппеты для сборки.

Локальные сниппеты

Для удобства и быстроты разработки были добавление локальные сниппеты (находятся в папке .vscode/snippets), которые работают благодаря плагину, описанному выше. Все сниппеты начинаются с префикса g-. В сниппетах пока только html (быстрое создание навигации, соцсетей, корректного тега picture с webp и avif и так далее).

Некоторые сниппеты тесно связаны с scss-миксинами, например кнопка-бургер. Сниппет g-burger создаст вам html-разметку бургера, а подключение миксина @include burger добавит для него стили, что крайне удобно.

Полный список сниппетов с поддержкой миксинов будет опубликован позже.

Готовые модули

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

Бургер меню

Вы можете очень быстро добавить рабочий бургер к себе на страницу, для этого нужно:

  1. В html вызвать сниппет g-burger
  2. На ваше потенциальное меню в html добавить атрибут data-menu
  3. В scss вызвать миксин burger
.burger { @include burger }
  1. Зайти в файл js/_functions.js и раскомментировать строку с подключением js-файла бургера
  2. Настроить стили показа меню под себя с помощью класса menu--active

Необязательно использовать функции именно в файле functions, делайте как удобно вам.

Модальное окно

Вы можете очень быстро добавить рабочее модальное окно к себе на страницу, для этого нужно:

  1. В html вызвать сниппет g-graph-btn. Он создаст кнопку для модального окна, ваша задача лишь заполнить атрибут data-graph-path
  2. Далее вызвать сниппет g-graph-modal. Он создаст базовую разметку окна. Ваша задача - сделать окно по макету, заполнить контент и обязательно обозначить атрибут data-graph-target с тем же значением, что и у data-graph-path
  3. Зайти в файл vendor.scss и раскомментировать строку с подключением файла graph-modal.min.css
  4. Зайти в файл js/_functions.js и раскомментировать строку с импортом и подключением библиотеки GraphModal

Необязательно использовать фунции именно в файле functions, делайте как удобно вам.

Управление скроллом

Вы можете отключать\включать скролл на странице (работает даже на iPhone). Для этого нужно:

  1. Зайти в файл js/_functions.js и раскомментировать строку с импортом функций disableScroll, enableScroll. Важно!. Если на странице присутствуют блоки с фиксированным позиционированием (например, шапка), добавьте ей класс fix-block, чтобы этот блок не прыгал при отключении скролла.

Необязательно использовать функции именно в файле functions, делайте как удобно вам.

Табы

Вы можете очень быстро добавить рабочие табы к себе на страницу, для этого нужно:

  1. В html вызвать сниппет g-tabs. Он создаст разметку для табов, ваша задача лишь заполнить атрибут data-tabs
  2. Для класса .tabs вызвать миксин tabs в scss
  3. Зайти в файл js/_functions.js и раскомментировать строку с импортом и подключением библиотеки GraphTabs

Необязательно использовать функции именно в файле functions, делайте как удобно вам.

Throttle-функция

Чтобы сгладить управление частоиспользуемыми событиями, вы можете использовать готовую функцию throttle. Для этого нужно:

  1. В нужном месте импортировать функцию throttle()
  2. Написать нужную вам функцию, например, func()
  3. Создать переменную, в которую поместить вызов вашей фукнции внутри throttle, например: let f = throttle(func)
  4. Использовать эту переменную как функцию в вызове, например: window.addEventListener('resize', f)

Необязательно использовать функции именно в файле functions, делайте как удобно вам.

Фикс фулскрин блоков

Нередко блоки с высотой 100vh вызывают проблемы в мобильных браузерах. Решить это поможет готовый модуль fix-fullheight:

  1. Раскомментируйте строку с импортом файла fix-fullheight.js
  2. Назначьте на нужный вам блок высоту не 100vh, а var(--vh)

Для этой функции используется ранее упомянутый throttle. Вы можете убрать его, либо изменить время внутри файла fix-fullheight.js.

Необязательно использовать функции именно в файле functions, делайте как удобно вам.

Примечание

Все данные функции вы можете вызывать там где вам удобно, необязательно именно в _functions.js. Тут все зависит уже от проекта.

Заключение

Спасибо всем, кто использует сборку! Если вы заметили какую-либо ошибку, пришлите пожалуйста ишью с подробным описанием проблемы, я все смотрю и постараюсь решить. Спасибо!

About

My gulp settings


Languages

Language:JavaScript 62.4%Language:SCSS 27.4%Language:PHP 5.8%Language:HTML 4.4%