emulsify_tools

Support Emulsify Drupal with child theme generation and Twig helpers

Emulsify Tools is a companion module for Emulsify (parent theme). It provides the supported Drush workflow for generating Emulsify 6.x child themes, along with Twig helpers that make component-driven Drupal templates easier to build and maintain.

Emulsify Tools is designed for projects using the Emulsify parent theme. It helps teams create generated child themes, keep Drupal template attributes manageable, and use consistent BEM class patterns across Twig templates.

What Emulsify Tools provides

• A Drush command for generating Emulsify child themes.
• The drush emulsify command alias for a shorter child theme generation workflow.
• The fully qualified drush emulsify_tools:bake command.
• A bem() Twig function for generating BEM-style class names.
• An add_attributes() Twig function for merging Drupal template attributes.
• Compatibility support for the Emulsify Drupal 6.x release line.

Current stable release: 1.x

The 1.x release line supports the Emulsify 6.x workflow. It is intended for Drupal projects using Emulsify as a parent/base theme and Emulsify Tools as the child theme generation helper.

The latest 1.x updates improve the child theme generation command, align compatibility with Emulsify 6.x, and add safer behavior when generating themes. The generator now validates that the Emulsify parent theme and Whisk source directory are available before copying files, and it fails safely when the destination child theme already exists.

Use Emulsify Tools 1.x if you are maintaining an Emulsify 6.x project or need the current supported Drush-based child theme generation workflow.

Companion support: Emulsify 6.x

Emulsify Tools 1.x is paired with Emulsify 6.x. Emulsify provides the parent theme, Webpack-based frontend workflow, Storybook integration, and Whisk child theme source. Emulsify Tools provides the Drupal-side helper command that generates a project-specific child theme from that source.

Drupal core Starterkit-based generation is being prepared for the Emulsify 7.x release line. For Emulsify 6.x, Emulsify Tools remains the supported public child theme generation workflow.

Child theme generation

Emulsify projects should generate a custom child theme and do project-specific development there. Emulsify Tools provides two equivalent Drush commands for this workflow:

drush emulsify my_theme

Or:

drush emulsify_tools:bake my_theme

The generated child theme uses emulsify as its runtime parent theme and should be created in your Drupal custom theme directory, such as web/themes/custom/my_theme in a Composer-based Drupal project.

After generation, enable the child theme and set it as the default theme:

drush theme:enable my_theme -y
drush config:set system.theme default my_theme -y
drush cr -y

Then install frontend dependencies from the generated child theme:

cd web/themes/custom/my_theme
npm install
npm run develop

Twig helpers

BEM Twig function

The bem() Twig function builds BEM-style class names and returns them in a form that can be printed into Drupal template attributes.

<h1 {{ bem('title') }}>

Outputs:

<h1 class="title">

Modifiers can be passed as an array:

<h1 {{ bem('title', ['small', 'red']) }}>

Outputs:

<h1 class="title title--small title--red">

Elements can be generated by passing a block name:

<h1 {{ bem('title', ['small', 'red'], 'card') }}>

Outputs:

<h1 class="card__title card__title--small card__title--red">

Add attributes Twig function

The add_attributes() Twig function merges additional attributes with Drupal's template-level attributes and helps prevent those attributes from trickling down into child includes.

{% set additional_attributes = {
  "class": ["foo", "bar"],
  "data-example": ["example-value"]
} %}

<div {{ add_attributes(additional_attributes) }}></div>

It can also be used with the bem() function:

{% set additional_attributes = {
  "class": bem("foo", ["bar", "baz"], "foobar")
} %}

<div {{ add_attributes(additional_attributes) }}></div>

Installation

Install the current stable release with Composer:

composer require 'drupal/emulsify_tools:^1.0'

Emulsify Tools is typically installed alongside Emulsify Drupal:

composer require 'drupal/emulsify:^6.1'
composer require 'drupal/emulsify_tools:^1.0'

Related projects

• Emulsify: the Drupal parent/base theme that uses Emulsify Tools for child theme generation.
• Emulsify Core: frontend build tooling, Storybook integration, Sass, JavaScript, and Twig support.
• Emulsify CLI: component scaffolding and optional system-based component installation.
• Emulsify UI Kit: optional starter components and design system patterns.

Documentation

For installation, usage, and Emulsify workflows, see the Emulsify documentation.