Bricks are reusable frontend modules for themes. They can contain templates, styles, images, fonts, resource bundles and JavaScript.

The idea of bricks is to split frontend features, special views or other functionality, like ImageMaps or Responsive Images into small modules instead of providing a big chunk like a basic theme. Technically, every brick is a package. By declaring everything it requires in its package.json (for example, its dependencies to third-party packages or other bricks) a brick is self-contained.

A brick can be used by a theme just by adding it as a dependency in the theme's package.json. The build process will provide everything the brick needs in order to be usable.

There are two kinds of bricks in the workspace. API bricks are provided in the lib/bricks folder. They are meant to be used directly in your theme or your bricks, and provide core functionality. While some bricks only provide helpers in form of FreeMarker Libraries and SCSS Mixins, some already contain generic views in form of FreeMarker Templates that can be adjusted via template parameters or styling that can be controlled via SCSS variables.

Example bricks are examples of how you can use the Frontend Workspace and API bricks. They mostly contain fully fledged layouts with special behavior in different devices. They are not meant to be used directly in your theme, since they can be changed or removed in new releases without warning. Rather than providing a large set of configuration via parameters, variables and settings they are meant to be changed directly by creating a copy (see Section 5.4, “Using an Example Brick”).

Just like a theme a brick is a package which consists of various web resources located in its src folder. It is meant to be a reusable frontend module that is easy to add to a theme without having to know much about its inner structure. Example 4.5, “ File structure of a brick ” shows the filesystem structure of a brick:

bricks/
└── [$brick-name]/
    ├── src/
    │   ├── freemarkerLibs/
    │   │   └── [$brick-name].ftl
    │   ├── fonts/
    │   │   └── example.woff2
    │   ├── img/
    │   │   └── example.png
    │   ├── js/
    │   │   └── index.js
    │   ├── l10n/
    │   │   └── [$brick-name]_en.properties
    │   ├── sass/
    │   │   ├── partials/
    │   │   ├── variables/
    │   │   ├── _partials.scss
    │   │   └── _variables.scss
    │   └── templates/
    ├── .prettierignore
    ├── .prettierrc
    └── package.json

Bricks can provide JavaScript, SCSS, templates, localization and other web resources just like images and fonts. The theme build process knows about the file system layout of bricks so it can easily integrate the different parts into the bundled theme that is used on a website.

Just like every package bricks can depend on other packages using their package.json. As the package.json supports multiple kinds of dependencies CoreMedia encourages using (normal) "dependencies" for most of the use cases (especially when depending on other bricks) and "devDependencies" when requiring specific tools (for example, test frameworks) that should not be installed when just using the brick in a theme or in another brick.

When a brick depends on another brick, it will always include the other brick's web resources, so only direct dependencies need to be handled by a theme.

Note

Bricks may not depend on themes but they may depend on other bricks if necessary. If you're creating your own bricks, be aware to avoid cyclic dependencies between them even if this will not break the building of themes. CoreMedia recommends using the script pnpm create-brick name to create a new brick, see Section 5.2, “Creating a New Brick”.

A brick always provides JavaScript using the "main" entry in the package.json. For CoreMedia's bricks src/js/index.js is used. In case no "main" entry is provided the lookup mechanism will check if there is a index.js directly below the brick folder which is the default behavior of Node JS.

Every brick also provides two SCSS files: _variables.scss and _partials.scss directly below src/sass/. The _variables.scss represents the variables or configuration layer and only defines variables while never producing any output. The _partials.scss represents the partials or output layer which assumes that it is imported after the configuration. It creates the actual CSS rules based on the values of the variables.

The separation of these two layers is crucial and should be taken into account when creating an own brick. More information about the SASS structure can be found in Section 4.4, “Sass Files”.

Just like a theme a brick can provide templates that will be considered by the view lookup mechanism. Templates can be found below src/templates. Technically bricks can override the templates of other bricks. The order in which the templates are copied is determined by the dependency tree. Considering a theme is the root, leaf bricks will always be copied first moving the tree down to the root so templates of dependent bricks are always copied before the depending brick.

Localization follows the same pattern as described in Section 4.6, “Localization”. The resource bundle files can be found directly below src/l10n/.

Other web resources just like images and fonts are not just copied into a theme but will be gathered by the theme build process when analyzing the JavaScript and the CSS code produced by the SCSS build. Both types can reference other web resources. While in JavaScript require statements are used, in CSS code all data URL directives will be parsed to collect other web resources.

As the location in which the web resources are placed is determined by the build process, bricks do not make any assumptions about the file structure of the bundled theme. This also means that data URLs and require statements are the only place where other web resources are referenced.

Caution

To keep the bricks maintainable and easy to upgrade it is highly recommended to make no changes to the files and folders in the lib/bricks directory, except creating your own brick. Otherwise, upgrading via a patch file may no longer be possible.