gulp-nunjucks-starter-kit

Инструмент для создания статических сайтов, и их проектирования с помощью шаблонизатора Nunjucks и сборки с помощью Gulp+Webpack используется компонентный подход + разделение данных от разметки.

Точечная пересборка (Incremental Build)

C версии v2025.08.12 сборка работает инкрементально:

Более подробно про новшества: build-system.ru.md

Что меняется	Что пересобирается
Nunjucks страница / компонент / секция / шаблон	Только страницы, реально затронутые изменением (вычисляется через карту зависимостей).
JSON-данные для страницы	Одна соответствующая страница.
JSON компонента/секции/шаблона	Страницы, которые используют эту сущность.
SCSS-partial	Точный репак `main.scss`; в dev без `cssnano`, в build — с минификацией.
Картинки / шрифты	Копируются исключительно изменённые файлы (`since: lastRun`).

Как это работает

Карта зависимостей (components ↔ sections ↔ templates ↔ pages) создаётся при первом запуске dev-сессии и хранится в памяти.
Любое изменение файла проходит через «детектор» (detectChangeType) → находим все страницы, которые реально нужно перерендерить.
Для стилей точечный ререндер = одна сборка main.scss (парсится за миллисекунды, потому что cssnano выключен в dev).
Для ассетов задействуется since: lastRun(task), так что копируется только новое.

Зачем: проект с 14 + страницами и десятками секций перестаёт «собираться полностью» после каждой правки. Горячий отклик в dev остаётся < 300 мс, а использование RAM/CPU контролируется монитором.

Что помнить

Изменения в Global.json / Common.json ⇒ полная пересборка (логично: эти данные видят все страницы).
Правило проекта: файлы в templates/ не вызывают компонентов — поэтому findComponentUsages игнорирует templates/**, что экономит время поиска.

Монитор ресурсов (RAM / CPU)

В режиме разработки запускается вспомогательный таск monitor. Он раз в 10 секунд снимает показатели процесса Gulp (RAM и CPU) и, при превышении порогов, выводит предупреждение в консоль и системное уведомление.

Порог	Значение по умолчанию	Настраивается
RAM	1500 MB	`settings.monitor.maxMemoryMB`
CPU	250 %*с за 10 с	`settings.monitor.maxCpuPercent`
Интервал опроса	10 000 мс	`settings.monitor.intervalMs`

Отключить монитор можно флагом --no-monitor (npm run dev -- --no-monitor).

Оповещения

Оповещения фатальной ошибки при старте, и успешного старта/сборки проекта теперь выводятся правильно.

Примечание:

Актуальные изменения смотри в CHANGELOG.md и на странице релиза.

Репозиторий переведён в режим "Шаблонного репозитория", подробности можно посмотреть тут

Установка

Версия Node.js

Рекомендуемые версии node.js (проект тестировался именно на нижеследующих версиях node.js):

lts/iron или выше

Установка Node.js

Для работы необходимо выполнить следующие шаги:

Установите в свою систему с официального сайта NodeJS или с помощью NVM (Node Version Manager)
Установите gulp глобально (т.е. для всей системы):

npm i --global gulp-cli

Клонируйте репозиторий:

git clone https://github.com/Template-Craft/gulp-nunjucks-starter-kit.git

Или создайте шаблон репозитория подробнее смотрите в справке. Для этого в системе должен быть установлен инструмент github-cli инструкция тут, а так же вы должны быть авторизованы.

Создание репозитория в интерактивном режиме:

gh repo create

Создайте новый удалённый репозиторий на основе этого репозитория (используя его как шаблон) и клонируйте его локально:

gh repo create MyBestProject --public --template https://github.com/Template-Craft/gulp-nunjucks-starter-kit.git

Клонируйте локально только что созданный репозиторий:

gh repo clone YourGithubName/MyBestProject path_to_dir

Или используйте объединённую команду для создания и копирования репозитория:

gh repo create MyBestProject --public --template https://github.com/Template-Craft/gulp-nunjucks-starter-kit.git && gh repo clone YourGithubName/MyBestProject path_to_dir

Где YourGithubName/MyBestProject - это адрес вашего репозитория, YourGithubName - имя использованное в профиле Github

После установки необходимого, перейдите в папку со скачанным проектом
Установите необходимые зависимости инструмента, находясь в родительском каталоге проекта и введя в терминал команду: npm i

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

После успешного выполнения предыдущих шагов, настало время запустить проект! Рассмотрим команды для запуска:

команды

Режим разработчика, выполняет запуск локального сервера с проектом:

npm run dev

Режим сборки проекта, осуществляется сборка проекта в директорию build

npm run build

После успешного старта/сборки проекта, возникнет небольшое всплывающее окошко об информации в каком режиме находится инструмент (сборка/разработка)

дополнительные команды

В проекте так-же существует дополнительная консольная программа помощник (директория: ./cli-app/cli-tools.mjs), помогающая быстро создавать компоненты (в соответствии с архитектурой файлов и папок проекта), а так же импортировать файлы стилей компонента в файл _components_import.scss - который в свою очередь подключается в главный файл стилей проекта: main.scss. Помимо этого доступны и другие фунции, подробнее ниже:

Что-бы воспользоваться дополнительным инструментом, наберите в терминале:

node ./cli-app/cli-tools.mjs

Или:

node ./cli-app/cli-tools.mjs -help

Действия выше вызовут справку по командам и опциям утилиты.

Доступные команды и опции cli-app

Создание файлов компонента:

node ./cli-app/cli-tools.mjs create --component ComponentName

Или:

node ./cli-app/cli-tools.mjs create -c ComponentName

Данная команда создаст файлы компонента, подробнее о команде и опциях смотрите:

node ./cli-app/cli-tools.mjs create -help

Импорт файлов стилей компонента в `_components_import.scss`

node ./cli-app/cli-tools.mjs import --style ComponentName

Или

node ./cli-app/cli-tools.mjs import -s ComponentName

Необходимо просто передать название компонента, программа ищет компонент и его фалы в директории: ./src/views/components

Данная команда подключит файл стилей компонента в _components_import.scss, подробнее о команде и опциях смотрите:

node ./cli-app/cli-tools.mjs import -help

Архивирование директорий и файлов

node ./cli-app/cli-tools.mjs archive -o="tgz" -p="dirName"

Или

node ./cli-app/cli-tools.mjs archive --option="tgz" --path="dirName"

Необходимо передать 2 аргумента: опция - это формат желаемого архива (всего доступно 3 опции/формата: tgz, tar, zip) и путь до директории или файла который необходимо архивировать.

Данная команда создаст архив, подробнее о команде и опциях смотрите:

node ./cli-app/cli-tools.mjs archive -help

Оптимизация изображений с помощью imagemin

Минификация файлов:

node ./cli-app/cli-tools.mjs imagemin --minify="all" --input="./src/assets/img/" --output="./build/assets/img/"

Или

node ./cli-app/cli-tools.mjs imagemin -m="all" -i="./src/assets/img/" -o="./build/assets/img/"

Необходимо передать 3 аргумента: 1 - minify режим минимизации название аргумента = формат файла (all, gif, jpeg, png, svg); 2 - input - путь до директории с исходными файлами; 3 - output - путь до директории в которую попадут файлы после обработки;

Конвертация файлов:

node ./cli-app/cli-tools.mjs imagemin --convert="webp" --input="./src/assets/img/" --output="./build/assets/img/"

Или

node ./cli-app/cli-tools.mjs imagemin -c="webp" -i="./src/assets/img/" -o="./build/assets/img/"

Необходимо передать 3 аргумента: 1 - convert режим конвертации, название аргумента = формат файла (webp); 2 - input - путь до директории с исходными файлами; 3 - output - путь до директории в которую попадут файлы после обработки;

Подробнее о команде и опциях смотрите:

node ./cli-app/cli-tools.mjs imagemin -help

Конвертация svg в base64

node ./cli-app/cli-tools.mjs base64Converter --mode="single" --path="./src/assets/img/yourSVG.svg"

Или

node ./cli-app/cli-tools.mjs base64Converter -m="single" -p="./src/assets/img/ic-message-white.svg"

Необходимо передать 2 аргумента: 1 - mode режим конвертации, название аргумента - это кол-во обрабатываемых файлов (single, all); 2 - path - путь до директории с исходными файлами;

Примечание:

В режиме all необходимо передать путь до директории с файлами, она будет просканированна конвертации подвергнутся только svg файлы, далее создастся файл base64-output.txt в котором будут данные о конвертации (название и путь до файла и его base64 код).

Подробнее о команде и опциях смотрите:

node ./cli-app/cli-tools.mjs base64Converter -help

Так же в package.json файле, в разделе scripts зарегистрированы команды для быстрой демонстрации cli-tools, а именно команды по архивации директории build, сначала произойдёт сборка проекта, далее выполнится команда по архивации директории.

команды для архивации в разделе scripts:

команды	описание
`npm run build:archive:tgz`	собирает из исходников проект и упаковывает в tar.gz архив папку с собранным проектом.
`npm run build:archive:tar`	собирает из исходников проект и упаковывает в tar архив папку с собранным проектом.
`npm run build:archive:zip`	собирает из исходников проект и упаковывает в zip архив папку с собранным проектом.

Структура проекта и соглашений об именовании файлов

Структура директории проекта

./src
├── assets
│   ├── fonts
│   ├── img
│   ├── sprites
│   └── styles
│       ├── defaults
│       └── main
│           └── _sections
├── scripts
│   └── main
└── views
    ├── components
    │   ├── Footer
    │   └── Header
    ├── data
    ├── pages
    ├── sections
    └── templates

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

Правила для шаблонов nunjucks -> Все компоненты должны именоваться в стиле PascalCase, остальные файлы (кроме файлов в директории ./src/views/pages) должны именоваться в одном из стилей snake_case (пример: header_top.njk) или camelCase (пример: headerTop.njk);

Правила для стилей SCSS/SASS -> все компоненты, куски секций и прочией файлы должны именоваться в стиле snake_case пример: header_top.scss;

а так же, если это файлы, которые являются частью какого-то другого файла, то перед названием должны использовать (префикс) то-же правило распространяется и на файлы стилей компонент! нижнее_подчеркивание _ пример: _nav_item.scss;

Шаблоны nunjucks src/views/:

все компоненты создаются и находятся в соответствующей папке т.е. src/views/components/**/*
данные компонент находятся по пути: src/views/data/*.json
страницы проекта находятся по пути: src/views/pages/*
секции проекта находятся по пути: src/views/sections/* если многостраничный режим, то следует в директории с секцией создать поддиректории (используя стиль snake_case) с названиями страниц сайта и складывать в них секции зависящие от этих страниц! (перед названием секции не забываем ставить префикс нижнее_подчеркивание _) пример: src/views/sections/general_section/_header_top.njk
так же существует раздел шаблонов, находится он: src/views/templates/* -> можно использовать для хранения там файлов с содержимым html <head></head> и прочими повторяющимися штуками.

Файлы стилей scss src/assets/styles/:

все файлы стилей подключаются в главный файл стилей main.scss но gulp отслеживает абсолютно все стили находящиеся в родительской директории и в поддерикториях.
директории в которых находятся стили подключаемые к файлу main.scss следует как и содержимое директорий именовать согласно стилю snake_case, а так же использовать префикс нижнее_подчеркивание перед названием файла/директории;
если у нас подразумевается многостраничный режим вёрстки, то в директории src/assets/styles/_main/ следует создавать поддериктории с названиями страниц и уже во внутрь складывать файлы стилей зависящие от этих страниц, пример: src/assets/styles/_main/_general_page/_header_top.scss
директория src/assets/styles/_defaults/ - для складирования туда сетки, всяких helper`ов, миксинов и дефолтных для проекта состояний, подключения шрифтов и т.д.

Файлы скриптов js/mjs src/scripts/

все файлы скриптов обрабатываются с помощью babel+webpack, в корневой директории расположения оных, есть две директории main и vendor
в директории main - находится наш главный файл main.mjs, допустимо плодить различные дир-рии и подключать просто всё это в main.mjs
в директории vendor - находится файл скриптов в которые будут подключаться сторонние библиотеки, необходимые на стороне клиента в качестве полноценных библиотек.

Директория assets src/assets/

храним в ней шрифты, картинки, и прочий медиа-мусор

последние обновления описания: 13.08.2025

Name		Name	Last commit message	Last commit date
Latest commit History 164 Commits
.vscode		.vscode
cli-app		cli-app
gulp		gulp
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
babel.config.json		babel.config.json
build-system.ru.md		build-system.ru.md
eslint.config.mjs		eslint.config.mjs
gulpfile.mjs		gulpfile.mjs
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

gulp-nunjucks-starter-kit

Точечная пересборка (Incremental Build)

Как это работает

Что помнить

Монитор ресурсов (RAM / CPU)

Оповещения

Установка

Версия Node.js

Установка Node.js

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

Доступные команды и опции cli-app

Создание файлов компонента:

Импорт файлов стилей компонента в `_components_import.scss`

Архивирование директорий и файлов

Оптимизация изображений с помощью imagemin

Конвертация svg в base64

Структура проекта и соглашений об именовании файлов

About

Uh oh!

Releases 10

Packages

Uh oh!

Contributors 2

Uh oh!

Languages

License

Template-Craft/gulp-nunjucks-starter-kit

Folders and files

Latest commit

History

Repository files navigation

gulp-nunjucks-starter-kit

Точечная пересборка (Incremental Build)

Как это работает

Что помнить

Монитор ресурсов (RAM / CPU)

Оповещения

Установка

Версия Node.js

Установка Node.js

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

Доступные команды и опции cli-app

Создание файлов компонента:

Импорт файлов стилей компонента в _components_import.scss

Архивирование директорий и файлов

Оптимизация изображений с помощью imagemin

Конвертация svg в base64

Структура проекта и соглашений об именовании файлов

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Импорт файлов стилей компонента в `_components_import.scss`

Packages