Руководство по переходу на версию 2.0.0

Во время перехода на новые версии следует:

• Очистить результаты прошлых сборок — команда enb make clean.

• Собирать с новыми технологиями без учета кэша — команда enb make -n.

Это нужно для того, чтобы технологии отработали правильно, не опираясь на результаты предыдущих сборок.

В версии 2.0.0 изменения, ломающие обратную совместимость, связаны с:

• порядком файлов

• технологией deps-old

Порядок файлов

Поменялись правила упорядочивания списка файлов по нескольким суффиксам (расширениям). Теперь файлы группируются по именам БЭМ-сущностей, а не по суффиксам (расширениям). Изменения связаны с упорядочиванием:

• БЭМ-сущностей,

• уровней переопределения.

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

БЭМ-сущность vs. суффикс

Файлы должны быть отсортированы сперва по имени сущности, и только потом по суффиксу.

Было:

file.ext
file-2.ext
file.ext-2
file-2.ext-2

Стало:

file.ext
file.ext-2
file-2.ext
file-2.ext-2

Уровень переопределения vs. суффикс

Файлы должны быть отсортированы сперва по уровню, и только потом по суффиксу.

Было:

level/block/block.ext
level-2/block/block.ext
level/block/block.ext-2
level-2/block/block.ext-2

Стало:

level/block/block.ext
level/block/block.ext-2
level-2/block/block.ext
level-2/block/block.ext-2

Группировка по суффиксам

Новый подход может сломать сборку для тех случаев, когда ожидалось, что все файлы одной технологии попадут в сборку раньше, чем все файлы другой технологии. Например, чтобы файлы с суффиксом css оказались раньше, чем с ie.css.

Если нужно изменить порядок подключаемых файлов — необходимо добавить дополнительную логику в ту технологию, от которой ожидается подобное поведение. Иначе говоря, технология сборки сама должна решать какие файлы и в каком порядке необходимо собирать.

В случае со сборкой CSS-файлов для IE можно отдельно собрать обычный CSS, отдельно CSS для IE, а потом склеить файлы.

var bemTechs = require('enb-bem-techs'),
    CSSTech = require('enb/techs/css'),
    FileMergeTech = require('enb/techs/css');

module.exports = function (config) {
    config.node('bundle', function (node) {
        node.addTechs([
            // Получаем FileList
            node.addTechs([
                [FileProvideTech, { target: '?.bemdecl.js' }],
                [bemTechs.levels, levels: ['blocks']],
                [bemTechs.deps],
                [bemTechs.files]
            ]);

            // Собираем CSS-файлы без IE
            [CSSTech, { target: '?.pure.css', sourceSuffixes: ['css'] }],
            // Собираем CSS-файлы с IE
            [CSSTech, { target: '?.ie.css', sourceSuffixes: ['ie.css'] }],
            // Склеиваем собранные файлы
            [FileMergeTech, {
                sources: ['?.pure.css', '?.ie.css'],
                target: '?.css'
            }]
        ]);
        node.addTarget('?.css');
    });
};

Тогда код из файлов с суффиксом css будет гарантированно выше, чем код из файлов с суффиксом ie.css.

@import "common.blocks/button/button.css";
@import "common.blocks/button/button_hovered.css";
@import "desktop.blocks/button/button.ie.css";
@import "desktop.blocks/button/button_hovered.ie.css";

Технология deps-old

Рекомендация: если вы не используете include: false в deps.js-файлах, и на вашем проекте нет циклических must-зависимостей, попробуйте перейти на технологию deps, т.к. она работает значительно быстрее.

В технологии deps-old была исправлена ошибка, при которой в определенных условиях не выполнялись требования некоторых must-зависимостей. В этих случаях порядок попадания файлов в сборку не гарантирует корретной работы тех БЭМ-сущностей, для которых не выполнятся требования must-зависимостей.

Важно: алгоритм раскрытия зависимостей был полностью переписан.

Несмотря на то, что мы пытались полностью сохранить «привычный» порядок при раскрытии зависимостей, единственной гарантией правильной сборки является наличие правильно написанных deps.js-файлов.

Если сборка работает без ошибок, это еще не значит, что все deps.js-файлы написаны правильно.

Помимо синтаксических ошибок и опечаток в deps.js-файлах можно забыть указать зависимости, необходимые для одной из БЭМ-сущностей, и это не обязательно приведет к ошибке.

Пример

В декларации бандла описаны необходимые блоки.

exports.blocks = [
    { name: 'page' },
    { name: 'input' },
    { name: 'button' }
];

У блока page есть BEMHTML-реализация, поэтому необходимо добавить зависимость от базовых шаблонов.

{
    mustDeps: 'i-bem'
}

Предположим, что у блоков input и button нет зависимостей, хотя BEMHTML-реализации тоже есть.

В большинстве случаев после сборки блок i-bem попадет перед остальными блоками, это обеспечит правильную работу шаблонов для всех остальных блоков (input и button).

exports.deps = [
    { block: 'i-bem' },
    { block: 'page' },
    { block: 'input' },
    { block: 'button' }
];

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

exports.blocks = [
    { name: 'button' },
    { name: 'page' },
    { name: 'input' }
];

exports.deps = [
    { block: 'button' },
    { block: 'i-bem' },
    { block: 'page' },
    { block: 'input' }
];

Таким образом, после обновления на enb-bem-techs@2.0.0 порядок БЭМ-сущностей в раскрытой декларации бандла может отличаться. Если не все необходимые зависимости были указаны в deps.js-файлах, результат сборки может оказаться неправильным.