marmelad

Заготовка фронтенд проекта для продвинутых и начинающих 🤘. Хорошо подходит для поддержания единой структуры проектов в команде и легкого переиспользования готовых блоков между проектами, благодаря БЭМ подходу к организации файловой структуры и данных проекта.

Зависимости marmelad устанавливаются один раз и в будущем только обновляются, т.е. нет необходимости устанавливать кучу npm зависимостей для каждого проекта. Как следствие, экономия дискового пространства и возможность создания и работы в проектах без интернета.

Содержание

• Установка
  • Проблемы установки глобальных модулей для macOS и Linux
  • Из npm
  • Для разработчиков
  • Для определённого проекта
• Marmelad CLI
  • init [options] инициализация
  • dev [options] старт сборки
  • cp <name> создание страницы
  • cb <name> [options] создание блока
  • mv <oldName> <newName> [options] переименование блока
  • lint
  • dist релизные задачи
  • pack [name] [options] архивирование проекта
• Marmelad TCI
• Структура проекта
• Шаблоны/Блоки
  • Lagman
• Данные для шаблонов/блоков
  • incw расширение
• Сборка стилей
  • Post CSS плагины
• Bootstrap
  • Bootstrap как донор

Внимание

Вам нужно установить java для работы с node-w3c-validator.

Установка

Не пытайтесь установить marmelad путём копирования файлов сборщика с Windows на Linux. Для разных ОС устанавливаются разные зависимости. Пользуйтесь доступными способами для установки.

Проблемы установки глобальных модулей для macOS и Linux

По умолчанию npm устанавливает пакеты локально в ваших проектах. Вы также можете установить установочные пакеты глобально (например, npm install -g <package>) (полезно для приложений командной строки). Однако недостатком этого является то, что вам нужно получить root-права (или использовать sudo) для возможности глобальной установки.

Ознакомьтесь с руководством NPM для установки глобальных модулей Resolving EACCES permissions errors when installing packages globally

Установка из npm

npm i marmelad -g

Установка для разработчиков

git clone https://github.com/solversgroup/marmelad.git
cd marmelad
npm i
npm link # sudo npm link для linux

Установка для определённого проекта

Такой тип установки подходит, когда заказчик требует определённую структуру размещения файлов проекта, либо работа сборщика нуждается в переделке под проектные требования. Там может быть всё что угодно 😱.

Установка для определённого проекта производится также, как и Установка для разработчиков, отличается только в запуск.

Для инициализируя/запуская marmelad необходимо указать путь до исполняемого файла marmelad.

# node C:\marmelad\bin\marmelad.js
node <путь до директории клона>\bin\marmelad.js

Marmelad CLI

После установки из npm или для разработчиков, marmelad станет доступен в командной строке/терминале вашей системы как marmelad и mmd.

Для справки по командам marmelad необходимо ввести в консоль/терминал:

# без параметров
marmelad # или mmd
# или
marmelad --help # или mmd --help

Usage: marmelad [options] [command]

Заготовка фронтенд проекта для продвинутых и начинающих 🤘

Options:
  -v, --version                     output the version number
  -h, --help                        display help for command

Commands:
  init [options] [dir]              initialize new project
  dev [options]                     run development server
  cp <name>                         create new page
  cb [options] <name>               create new block
  mv [options] <oldName> <newName>  rename block
  lint                              lint project
  dist                              Release tasks for project
  pack [options] [name]             Archive project source code (default:tar.gz)
  help [command]                    display help for command

Commands help:
  marmelad [command] --help
  mmd [command] --help

Source files:
  <marmelad installed directory>\marmelad\bin\marmelad.js
Version:
  <marmelad version>

init [options] инициализация

Инициализация проходит в 3 этапа:

1. Копирование базовой заготовки с учётом переданных аргументов
2. Копирование в корень нового проекта вспомогательных файлов
3. Инициализация git репозитория в новом проекте

Для инициализации нового проекта, предназначена команда mmd init [options] [dir].

В случае, когда не передан параметр для папки инициализации, проект инициализируется в текущей директории открытой в терминале.

-c, --css - заменяет значение ключа app.css в settings.marmelad.js при копировании заготовки нового проекта. Далее этот ключ используется для команды создания блока mmd cb, для создания файлов css препроцессоров, с расширением установленным в app.css в settings.marmelad.js. Для добавления поддержки в проект на старом проекте после обновления до актуальной версии marmelad, необходимо добавить в settings.marmelad.js в объект app свойство css со значением/расширением требуемого css препроцессора.

-t, --test - необходим только для тестирования, в разработке проектов никакого смысла он не имеет.

--bootstrap - инициализирует новый проект с bootstrap, копируя его в базовую заготовку.

--bootstrap donor - автоматически включает bootstrap как донор.

[dir] - позволяет инициализировать проект в указанной папке. Например, mmd init new-and-awesome -t scss.

dev [options] старт сборки

Внимание если при запуске сборки вы видите ошибку code: 'MODULE_NOT_FOUND', то, скорее всего marmelad запускается в директории без предварительно созданного (mmd init) пустого marmelad проекта.

• dev стандартный запуск
• dev -a запуск сервера с парольной защитой, логин и пароль генерируются автоматически
• dev -a <login>@<password> запуск сервера с парольной защитой, логин и пароль устанавливаются вручную
• dev --build одноразовая сборка проекта без запуска слежения за изменениями и пересборки
• dev --proxy-mod режим сборки статики + проксирование уже живого сайта с копированием необходимых ресурсов (css,js) в определённую директорию рабочего сайта

dev --proxy-mod ошибка Error: Missing positive glob означает что вы не прописали в конфиге директории для копирования, по умолчанию они закомментированы.

cp <name> создание страницы

Файл страницы создаётся в директории marmelad/_pages, в имени файла расширение не указывается.

cb <name> [options] создание блока

Файлы блока создаются в директории marmelad/_blocks.

#.tci
cb new-block --t html,js

Создаст одноимённый блок, содержащий в себе все необходимые технологии.

# marmelad/_blocks
new-block
  ├─ new-block.html  # шаблон
  └─ new-block.js    # скрипты

Параметр --t позволяет указывать конкретно какие технологии необходимо создать. По сути в этот параметр можно перечислить через зяпятую сколько угодно форматов.

Формат для стилей указывать необязательно, если он не будет указан, то команда создаст файл с форматом стилей, который указан в settings.marmelad.js -> app.css.

mv <oldName> <newName> [options] переименование блока

Переименовать блок и все вхождения имени блока внутри файлов блока, в случае необходимости. Команда доступна в файле .tci.

# переименование файлов блока
mv old-block-name new-block-name

# переименование файлов блока и все вхождения внутри файлов блока
mv old-block-name new-block-name --hard

# холостой запуск с просмотром планируемых изменений в файлах
mv old-block-name new-block-name --dry --hard

lint W3C валидатор

Запуск W3C валидатора на уже собранном проекте.

Запуск W3C валидатора необходимо выполнять только после сборки проекта, иначе результаты валидации будут некорректны.

mmd dev --build && mmd lint

dist релизные задачи

Экспериментальная команда, пока никаких опций передать нельзя. Работает только с итоговыми файлами проекта, исходники никак не будут затронуты.

• Форматирование HTML-кода страниц проекта в папке сборки (static)
• Обжатие JS/CSS файлов и замена на обжатые в HTML шаблонах (обжимаются файлы без .min в названии)
• Прописывание хешей для подключаемых файлов, для сброса кэша
• Сортировка атрибутов HTML элементов

mmd dev --build && mmd dist

pack [name] [options] архивирование проекта

Упаковывает файлы проекта в tgz или zip архив.

• pack tgz архив
• pack -z, --zip zip архив
• pack -f, --folders [marmelad,static] упаковать только определённые директории в архив
• pack --nodt не подставлять дату и время создания в имя архива (отлючено по умолчанию)
• pack custom-name кастомное имя для архива, иначе имя архива позаимсвуется у корневой папки проекта

pack           # project_11072019-153012.tgz
pack my-name   # my-name_11072019-153012.tgz
pack -z        # project_11072019-153012.zip
pack -f static # project_11072019-153012.tgz только директория static
pack --nodt    # project.tgz без даты и времени в названии (отключено по умолчанию)

Marmelad TCI

TCI (text command interface) - добавлен в шаблон вёрстки и дублирует CLI команды marmelad (cp, cb), т.е. нет необходимости переходить в другую консоль/терминал, и в там уже выполнять доп. действия.

Теперь для этого есть файл .tci, все команды вводятся без префиксов mmd или marmelad.

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

├─ marmelad
│  ├─ _blocks                   # блоки
│  │   └─ some-block            # блок для примера
│  │       ├─ some-block.html   # шаблон блока
│  │       ├─ some-block.js     # скрипты блока
│  │       ├─ some-block.styl   # стили блока
│  │       └─ some-block.json   # данные блока
│  ├─ _pages                    # страницы
│  ├─ bootstrap                 # bootstrap, если нужен
│  ├─ iconizer                  # SVG-иконки для SVG-спрайта
│  │   ├─ colored               # цветные SVG-иконки
│  │   └─ icons                 # монохромные SVG-иконки
│  ├─ snippets                  # сниппеты BEML для редакторов
│  ├─ static                    # статика для вёрстки
│  ├─ styles                    # стили, styl или scss
│  ├─ .editorconfig             # конфиг для редактора
│  ├─ .tci                      # TCI команды marmelad
│  ├─ data.marmelad.js          # глобальные данные
│  └─ settings.marmelad.js      # настройки сборки
└─ static                       # итоговая сборка

Шаблоны/Блоки

• Шаблонизатор nunjucks
• БЭМ именование в HTML обеспечивает posthtml-bem

Lagman

Предназначен для оптимизации сборки шаблонов HTML на больших проектах, с большим кол-вом страниц.

Lagman строит связи/зависимости страниц от блоков или блоков от страниц. Что позволяет шаблонизатору понимать для какой из страниц изменился блок, и пересобирать HTML только тех страниц, в которых он используется.

Для правильной работы модуля, требуется строгое следовние правилам сборки блоков и страниц.

Блок должен содержать разметку БЭМ, с обязательным атрибутом block:

<div block="block-name" mods="red">
  ...
</div>

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

Данные для шаблонов/блоков

Данные для блока доступны в шаблонах по ключу с названием блока (если файл данных для блока создан и хоть чем-то заполнен), либо из data.marmelad.js (глобальные данные). Названия/ключи собственных данных блока преобразуются в camelCase.

incw расширение

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

{# ручная передача данных в шаблон #}
{% incw 'имя шаблона без расширения', {title: 'Example', subtitle: 'An example component'} %}

{# передача данных в шаблон из переменной #}
{% incw 'имя шаблона без расширения', app.lang %}

Данные переданные в incw доступны внутри шаблона по ключу _ctx.

{# подключение шаблона #}
{% incw 'avatar', { image: 'IMAGE URL', name: 'USERNAME'} %}

{# в шаблоне #}
<div block="incw-template">
  <img src="{{ _ctx.image }}" alt="">
  <span>{{ _ctx.name }}</span>
</div><!-- incw-template -->

Вложенные incw не получают _ctx родительского блока, только глобальные данные. Для передачи конкретных данных в вложенный incw необходимо передать данные явно для вкладываемого incw.

Сборка стилей

Сборка поддерживает stylus, scss, sass.

Post CSS плагины

• autoprefixer
• postcss-easing-gradients
• postcss-flexbugs-fixes
• postcss-inline-svg
• postcss-momentum-scrolling
• postcss-sort-media-queries

Bootstrap

Сборка bootstrap включается в settings.marmelad.js настройкой app.bts.use: true, все файлы собираются в корне сборке, в директории bootstrap.

Bootstrap как донор

Сборка bootstrap как донор включается в settings.marmelad.js настройкой app.bts.donor: true, при этом app.bts.use должен быть в false.

В случае использования bootstrap как донора для сборки стилей, файлы скриптов bootstrap копируются в директорию сборки js/vendors. Файлы стилей уже встраиваются так как вы их настроете, т.е. изменение файлов стилей bootstrap запускает сборку основных стилей, не запуская отдельную сборку стилей для bootstrap.

Iconizer

Iconizer претерпел изменения в плане способах его подключения и использования в шаблонах.

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

В шаблоне

{{ _icon('marmelad', { tag: 'span' }) }}

На выходе

<span class="svg-icon svg-icon--marmelad colored" aria-hidden="true" focusable="false">
  <svg class="svg-icon__link">
    <use xlink:href="#marmelad"></use>
  </svg>
</span>

Опции Iconizer

{{ _icon('<name>', {
  tag: 'div',
  type: 'icons',
  class: '',
  mode: 'inline',
  url: '',
}) }}

Функция icon из settings.marmelad.js -> iconizer передаётся в шаблонизатор nunjucks под именем _icon.

Типы SVG-спрайта

• icons - монохромные иконки, вырезаются все лишние атрибуты оформления
• colored - цветные иконки, вырезается только тег title

Пример использования цветной SVG-иконки

Для подключения цветной иконки необходимо добавить атрибут type="colored"

{{ _icon('marmelad', { type: 'colored' }) }}

Режимы подключения SVG-спрайта

• inline - спрайт внедряется в HTML-код страницы
• external - используется как отдельный файл, через обращение по URL его размещения

Миграция для Iconizer 5+

В settings.marmelad.js, необходимо удалить:

• paths.iconizer
• app.svgSprite

const paths = {
  // удалить
  iconizer: {
    ...
  },
};

const app = {
  // удалить
  svgSprite: {
    ...
  },
};

Добавить новый объект в settings.marmelad.js

const iconizer = {
  cssClass: 'main-svg-sprite',
  mode: 'inline', // external отдельный подключаемый файл спрайта (default:inline)
  dest: path.join(paths.dist, 'img'), // путь для собираемых спрайтов
  url: 'img', // путь до подключаемого спрайта iconizer.dest без paths.dist
  srcIcons: path.join(folders.marmelad, folders.iconizer.src, 'icons'),
  srcColored: path.join(folders.marmelad, folders.iconizer.src, 'colored'),
  icon: (name, opts) => {
    opts = Object.assign({
      tag: 'div',
      type: 'icons',
      class: '',
      mode: 'inline',
      url: '',
    }, opts);

    let external = '';
    let typeClass = '';

    if (opts.mode === 'external') {
      external = `${opts.url}/sprite.${opts.type}.svg`;
    }

    if (opts.type !== 'icons') {
      typeClass = ` svg-icon--${opts.type}`;
    }

    opts.class = opts.class ? ` ${opts.class}` : '';

    return `
      <${opts.tag} class="svg-icon svg-icon--${name}${typeClass}${opts.class}" aria-hidden="true" focusable="false">
        <svg class="svg-icon__link">
          <use xlink:href="${external}#${name}"></use>
        </svg>
      </${opts.tag}>
    `;
  },
  plugin: {
    mode: {
      symbol: { // symbol mode to build the SVG
        example: false, // Build sample page
      },
    },
    svg: {
      xmlDeclaration: false, // strip out the XML attribute
      doctypeDeclaration: false, // don't include the !DOCTYPE declaration
    },
  },
};

и не забыть добавить его в экспорт настроек

module.exports = {
  // добавить
  iconizer,
};

Задержка отдачи контента сервером latencyRoutes

В settings.marmelad.js app.bsSp необходимо добавить настройки для задержки отдачи сервером контента

// пример, для новых проектов по умолчанию задержка для /api
latencyRoutes: [
  {
    route: '/css',
    latency: 3000,
    active: true,
  },
],

Лицензия

MIT

Кодекс Поведения участника

Прочтите Кодекс Поведения участника

Логотип был взят и изменён, из набора иконок автора Jelly beans распространяемого под лицензией CC 3.0 BY с www.flaticon.com

В начало 🔝