Building a BEM project


In a BEM project, the code is divided into separate files (also called the source files).

To combine 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 a build process. The resulting files are called bundles in the BEM methodology.


Building a BEM project

Build tasks

The build performs the following tasks:

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

Build stages

In order to receive bundles as the result of the build, the following must be defined:

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

Defining the list of BEM entities

To include only the necessary BEM entitities in the build, you need to create a list of blocks, elements, and modifiers that are used on the pages. This list is called a declaration.

The build tool follows the declaration and adds only the listed BEM entities to the bundle. The example below shows bundling based on a list of BEM entities (declaration).


Building a BEM project

The declaration allows you to control the content of bundles that are output by the build. This eliminates unnecessary code, which could significantly increase the volume of bundles.

For more information about creating a declaration, see in 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.

The build tool gets the dependencies and adds all the BEM entities that the block requires. The example below shows a composite block with dependencies.


Example of a composite block

Dependencies allow you to build new blocks from existing ones. This frees you from unneeded copying and pasting.

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

Defining the order for connecting BEM entities to the build

The order for connecting BEM entities to the build depends on:

Dependencies and the order of connecting BEM entities to the build

In BEM, dependencies can affect how BEM entities are added to the build.

For more information about how to determine the order of connecting BEM entities to the build, see in DEPS syntax.

Redefinition levels and the order of connecting BEM entities to the build

In BEM, the final block implementation might be distributed across different redefinition levels. Each subsequent level extends or overrides the original block implementation. This is why it's important for the original implementation 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 the redefinition levels: common.blocks, desktop.blocks, and touch.blocks.


Redefinition levels

Redefinition levels allow you to change the block's appearance and behavior for different platforms.

For more information about using redefinition levels, see the examples:

Build result

The build result can output files for:

  • A section of a page (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).

The following example shows a build of the hello page.


File structure 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 structure of a BEM project after the build:


        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)

During the build, the following can be included in the project:

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

Build tools

The BEM methodology doesn't limit your choice of build tools in any way. You can use any assemblers that meet your project's needs.

We use the following build tools on the BEM platform:

Example of building a BEM project using ENB: Starting your own BEM project.

Example of building a BEM project using Gulp: Declarative JavaScript using BEM.

If you notice a mistake or want something to supplement the article, you can always write to us at GitHub, or correct an article using