build.en.md

Building a BEM project

• Introduction
• Build stages
• Build result
• Build tools

Introduction

In a BEM project, the code is divided into separate files (the source files). To combine the source files into a single file (for example, to put all CSS files in project.css, all JS files in project.js, and so on), we use the build process. The resulting files are called bundles in the BEM methodology.

Example

The build performs the following tasks:

• Combines source files that are spread out across the project's file system.
• Includes only the necessary blocks, elements, and modifiers in the project (BEM entities).
• Follows the order for including entities.
• Processes the source code during the build process (for example, compiles LESS code into CSS code).

Build stages

To receive bundles as the result of the build, define the following:

1. The list of BEM entities
2. Dependencies between them
3. Order for including them

The list of BEM entities

To include only the necessary BEM entities in the build, you need to create a list of blocks, elements, and modifiers used on the pages. This list is called a declaration. It allows you to get rid of unnecessary code that increases the bundle size.

The build tool bundles only the BEM entities that are included in the list. The example below shows bundling based on the declaration.

Example

For more information on how to create a declaration, see Ways to get declarations.

Defining dependencies

You can create BEM blocks based on other blocks. To do this, you need to define dependencies on them. Dependencies allow you to avoid unnecessary copying and pasting.

The build tool gets information about dependencies and adds all the BEM entities needed to implement a block. The example below shows a composite block.

Example

For more information on how to declare dependencies on other BEM entities and technologies, see Technology for declaring dependencies.

The order for including BEM entities in the build

The order for including BEM entities in the build depends on:

• Dependencies.
• Redefinition levels.

Dependencies and the order for including BEM entities in the build

In BEM, dependencies can affect the order of including BEM entities in the build. The mechanism of including the BEM entities depends on the DEPS entities that influence the inclusion priority in various ways.

For more information on how to determine the order of including BEM entities in the build, see the DEPS syntax section.

Redefinition levels and the order of including BEM entities in the build

In BEM, the final block implementation might be distributed across different redefinition levels. They allow you to change the representation and behavior of the blocks for different platforms. Each subsequent level extends or overrides the original block implementation. Therefore the original implementation has to be included in the build first, and then changes can be applied from all the redefinition levels. The example below shows a project with redefinition levels: common.blocks, desktop.blocks and touch.blocks. The build order is marked with numbers.

Example

For more information about using redefinition levels, see the Redefinition levels section.

Build result

The build result can output files for:

• A page fragment (for example, header.css or footer.css).
• A separate page (for example, hello.css and hello.js).
• The entire project (for example, project.css and project.js).

When building a single page or project, the resulting code can include:

• All BEM entities from the project's file structure (this significantly increases the code volume).
• Only the necessary BEM entities.

The example shows a hello page build.

Example

File system of a BEM project before the build:

blocks/                 # Directory containing blocks

bundles/                # Directory containing build results (optional)
    hello/              # Directory of the hello page (created manually)
        hello.decl.js   # List of BEM entities requires for the hello page

File system of a BEM project after the build:

blocks/

bundles/
    hello/
        hello.decl.js
        hello.css       # Compiled CSS file for the hello page (the hello bundle in CSS)
        hello.js        # Compiled JS file for the hello page (the hello bundle in JS)

Build tools

The BEM methodology doesn't limit your choice of build tools.

The BEM platform uses the following assemblers:

• ENB

  For more information on building a BEM project with ENB, see the Starting your own BEM project section.

• Gulp