Стартовый проект с gulp
Парадигма
- Именование классов по БЭМ, разметка в pug, стилизация Sass. См. как работать с CSS-препроцессорами и БЭМ.
- Каждый БЭМ-блок в своей папке внутри
src/blocks/
. Имена файлов в такой папке должны совпадать с именем блока. См. ниже про Блоки. - Есть файл конфигурации, определяющий попадание в сборку дополнительных файлов и неиспользованных в разметке блоков. Смотри
config.js
. - Можно использовать глобальные файлы:
src/js/script.js
— общий js, берётся в сборку по умолчанию,src/scss/print.scss
— стили печати, не берутся в сборку по умолчанию (см.config.js
).
- Список pug-примесей
src/pug/mixins.pug
генерируется автоматически и содержитinclude
существующих pug-файлов всех блоков. - Диспетчер подключения стилей
src/scss/style.scss
генерируется автоматически и содержит импорты стилевых файлов использованных в разметке блоков и импорты доп. файлов, указанных вconfig.js
. - Входная точка обработки js (
src/js/entry.js
) генерируется автоматически и содержитrequire
js-файлов использованных в разметке блоков и доп. файлов, указанных вconfig.js
. - Используется кодгайд (относительно жёсткий), его проверка делается перед коммитом или вручную (
npm run test
), ошибки выводятся в терминал. - Есть механизм быстрого создания нового блока:
node createBlock.js new-block
(создаёт папки и scss-файл). После имени нового блока можно дописать нужные расширения.
Установка
Требуются установленный git и Node.js (LTS).
- Открыть терминал, попасть в папку проектов, клонировать этот репозиторий:
git clone https://github.com/nicothin/NTH-start-project.git my-new-project
- Удалить историю разработки:
rm -rf .git
- Установить зависимости проекта:
npm i
(может быть долго, особенно на Windows).
Команды
npm start # запуск сервера разработки (сборка БЕЗ библиотеки блоков)
npm start deploy # отправка содержимого папки сборки на gh-pages (нужен репозиторий на github.com)
npm run build # сборка БЕЗ библиотеки блоков и без запуска сервера разработки
npm run wlib # запуск сервера разработки (сборка проекта с библиотекой блоков)
npm run test # проверка всех pug-, scss- и js-файлов на соответствие правилам (см. .pug-lintrc, .stylelintrc и eslintrc соответственно)
npm run test:pug # проверить только pug-файлы
npm run test:style # проверить только scss-файлы
npm run test:js # проверить только js-файлы
Структура
build/ # Папка сборки (результат работы над проектом)
src/ # Исходники
blocks/ # Блоки (подпапки с блоками)
favicon/ # Фавиконки (копирование прописать в config.js)
fonts/ # Шрифты (копирование прописать в config.js, подключение в src/blocks/page/page.scss)
img/ # Общие для всех блоков изображения (копирование прописать в config.js)
js/ # Общие js-файлы, в т.ч. точка сборки для webpack и общие модули
pages/ # Страницы проекта (при компиляции: src/pages/index.pug → build/index.html)
pug/ # Служебные pug-файлы (шаблоны страниц, примеси)
scss/ # Служебные стилевые файлы (диспетчер подключений, переменные, примеси)
Как это работает
При npm start
запускается дефолтная задача gulp:
- Очищается папка сборки (
build/
). - Записывается файл
src/pug/mixins.pug
с includ-ами pug-файлов всех блоков. - Компилируются файлы страниц (из
src/pages/**/*.pug
вbuild/*.html
). - Из скомпилированных html-файлов извлекаются все классы уровня БЭМ-блока. На основании этого списка будут построены диспетчер подключения стилей и список всех js-файлов проекта.
- Генерируются спрайты (если блоки спрайтов используются), в папку сборки копируются картинки блоков и доп. файлы из секции
addAssets
файлаconfig.js
. - Записывается диспетчер подключения стилей
src/scss/style.scss
, в котором:- Импорты файлов из секции
addStyleBefore
файлаconfig.js
. По умолчанию — SCSS-переменные и примеси. - Импорты файлов БЭМ-блоков, упомянутых в секции
alwaysAddBlocks
файлаconfig.js
. Таким образом, можно взять в сборку любой блок, даже если его css-класс не упоминается в разметке страниц. - Импорты файлов БЭМ-блоков, использующихся в разметке.
- Импорты файлов из секции
addStyleAfter
файлаconfig.js
.
- Импорты файлов из секции
- Записывается входная точка обработки скриптов
src/js/entry.js
, в которой:require
файлов из секцииaddJsBefore
файлаconfig.js
.require
файлов БЭМ-блоков, использующихся в разметке.require
файлов БЭМ-блоков, упомянутых в секцииalwaysAddBlocks
файлаconfig.js
.require
файлов из секцииaddJsAfter
файлаconfig.js
.
- Компилируется диспетчер подключения стилей (
src/scss/style.scss
). Результат обрабатываются плагинами PostCSS. - Обрабатывается входная точка Javascript (
src/js/entry.js
). Используется Webpack. - Запускается локальный сервер и слежение за файлами для пересборки.
Блоки
Каждый блок лежит в src/blocks/
в своей папке.
Возможное содержимое блока:
demo-block/ # Папка блока.
img/ # Изображения, используемые этим блоком (копируются в папку сборки).
demo-block.pug # Разметка (pug-примесь, отдающая разметку этого блока, описание API примеси).
demo-block.scss # Стилевой файл этого блока (без стилей других блоков).
demo-block.js # js-файл блока (без скриптов других блоков).
readme.md # Описание для документации, подсказки.
page
Особенный блок На теге <html>
по умолчанию прописан класс page
, что делает одноимённый блок «глобальным». В стилях этого блока прописываются:
- подключение сторонних шрифтов,
- смена боксовой модели,
- cтили шаблона (см.
src/pug/layout.pug
), - стилизация тегов по умолчанию (аналог Normalize.CSS).
Удобное создание нового блока
# формат: node createBlock.js ИМЯБЛОКА [доп. расширения через пробел]
node createBlock.js demo-block # создаст папку блока, demo-block.scss, подпапку img/ для этого блока
node createBlock.js demo-block pug js # создаст папку блока, demo-block.scss, demo-block.pug, demo-block.js, подпапку img/ для этого блока
Если блок уже существует, файлы не будут затёрты, но создадутся те файлы, которые ещё не существуют.
Сторонние npm-модули
Если нужно взять в сборку сторонний модуль, то после его установки (к примеру — npm i package-name
) нужно:
- Прописать
require
в js-файле проектного блока (там же писать всё, что касается работы с этим модулем). Если сторонний модуль нужен без привязки к какому-либо проектому блоку, прописатьrequire
вsrc/js/script.js
(см. пример в файле). - Если нужно брать в сборку стилевые файлы модуля, прописать их в секции
addStyleBefore
файлаconfig.js
(пример в файле). - Если нужно брать в сборку дополнительные файлы модуля, прописать их в
addAssets
файлаconfig.js
с указанием в какую папку их копировать (пример в файле).
Разметка
Используется pug.
Все страницы (см. src/pages/index.pug
) являются расширениями шаблонов из src/pug
(см. наследование шаблонов), в страницах описывается только содержимое «шапки», «подвала» и контентной области (см. блоки).
Каждый блок (в src/blocks/
) может (не обязан) содержать одноимённый pug-файл с одноименной примесью, который при старте сервера разработки будет взят includ-ом в файл src/pug/mixins.pug
.
Стили
Диспетчер подключений (src/scss/style.scss
) формируется автоматически при старте сервера разработки.
Каждый блок (в src/blocks/
) может содержать одноимённый scss-файл со стилями этого блока. Если блок используется в разметке (или упомянут в config.js#alwaysAddBlocks
), его scss-файл будет взят в сборку стилей.
Используемый постпроцессинг:
Стилевой код-гайд
Автопроверка с stylelint и плагинами. См. .stylelintrc
.
- БЭМ-именование:
__
— разделитель элемента,--
— разделитель модификатора. - Один Блок = один стилевой файл.
- Очередность селекторов:
- Инклуды примесей
- Стилевые правила сущности
- Медиаусловия
- Псевдоселекторы и псевдоэлементы
- Сторонние вложенные селекторы
- Элементы блока
- Модификаторы блока
Скрипты
Точка входа (src/js/entry.js
) формируется автоматически при старте сервера разработки. Точка входа обрабатывается webpack-ом (с babel-loader).
Для глобальных действий предусмотрен src/js/script.js
(см. config.js#addJsAfter
и config.js#addJsBefore
).
Каждый блок (в src/blocks/
) может (не обязан) содержать одноимённый js-файл. Если блок используется в разметке (или упомянут в config.js#alwaysAddBlocks
), его js-файл будет взят в сборку стилей.
Инлайн-скрипт
По умолчанию в шаблоне (src/pug/layout.pug
) прописана вставка в <head>
скрипта src/js/head-script.js
, в котором для узла <html>
указано:
- Убрать класс
no-js
и добавить классjs
. - Добавить класс с указанием названия браузера и ОС.
- Добавить класс
touch
илиno-touch
, в зависимости от типа интерфейса. - Добавить кастомное свойство
--vh
со значением в 1% высоты вьюпорта (значение пересчитывается при изменении размеров).
Нравится проект?
Ставьте звезду репозиторию и/или угостите меня кофе, переведя сколь угодно символическую сумму.