Single Directory Components in Drupal core: A comprehensive overview

Known for its robustness and flexibility, Drupal continues to evolve, providing developers with innovative tools to streamline their workflow. One of the most significant additions in recent releases has been the introduction of Single Directory Components (SDC) in Drupal Core. This feature promises to simplify the development process, improve component reusability and enhance the overall theme experience. This article looks at what SDCs are, their benefits, and how to implement them in your Drupal projects.

What are Single Directory Components?

Single Directory Components in Drupal are a way of encapsulating all the necessary files for a component in a single directory. This includes the component's templates, styles, JS and configuration files. By organising components in this way, developers can manage, reuse and maintain them more efficiently.

Advantages of individual directory components

Modularity and reusability

• SDCs promote a modular architecture where components can be easily reused in different parts of the site, reducing redundancy and maintenance.

Improved maintainability

• With all component-related files in one directory, they are easier to find and update, resulting in improved maintainability.

Streamlined development workflow

• SDCs simplify the development workflow by reducing the scattering of files across different directories. This organisation fits well with modern front-end development practices.

Consistency

• By encapsulating styles, scripts and templates together, developers can ensure a consistent implementation of components across the site.

Implementing Single Directory Components in Drupal

Each component needs a single directory for its assets. This directory must exist in a components/ subdirectory of your theme or module’s directory (so that Drupal can find it). A {NAME}.component.yml file containing metadata about the component. Creating a schema within your {NAME}.component.yml is mandatory for modules, but optional for themes. However, it's highly recommended.

Choose a name for your component. We will use button for our example. It should be unique within the theme. Components are namespaced, so several different themes could declare a button component.

button.component.yml

$schema: https://git.drupalcode.org/project/drupal/-/raw/10.1.x/core/modules/sdc/src/metadata.schema.json
name: Call to Action
description: Call to action button
props:
  type: object
  required:
    - text
  properties:
    text:
      type: string
      title: Text button
    modifiers:
      type: array
      items:
        type: string
      title: Class names

Then we need to define the HTML structure of your component in the Twig template file.

button.twig

<button class="btn {{ modifiers|join(' ') }}">
  {{ text }}
</button>

Let us apply some CSS to this button to give it a more appealing appearance. All you have to do is make a CSS file in the component directory including the name of your component.

button.css

.btn {
  background-color: #007bff;
  color: white;
  padding: 10px 20px;
  border: none;
  border-radius: 4px;
  cursor: pointer;
  &.primary {
    background-color: #0056b3;
  }
  &.secondary {
    background-color: #6c757d;
  }
}

We have the following file structure for the new button component in our theme: 

Image

To use a component we will need to know the component ID. This is the machine name of the module or theme that provides the component, plus the name of the component itself, separated by a colon. Examples:

{module}:{component} 
some_custom_module:button: where some_custom_module is the module name, and button is the component name
olivero:teaser: where olivero is the theme name, and teaser is the component name

In our case, we will use the component directly in the Twig template and use the {% include %} keyword. Edit the file node.html.twig and simply add the following code at the bottom:

  {% include 'theme_name:button' with { text: 'Click Me', modifiers: ['primary'] } only %}

This will include our button component on the node page. Here is the outcome.

Image

Learn more about the other new features of Drupal 11 here.

Conclusion

The introduction of Single Directory Components in Drupal Core marks a significant step towards modernising the front-end development workflow in Drupal. By consolidating all component-related files into a single directory, developers can achieve greater modularity, maintainability and consistency. The use of SDCs not only streamlines the development process, but also aligns Drupal with modern web development practices, making it a more powerful and user-friendly CMS.

As Drupal continues to evolve, features like SDCs will undoubtedly play a crucial role in improving the developer experience and the overall quality of Drupal websites. Our Drupal agency is here to help you dive in, explore Single Directory Components, and start building more modular and maintainable Drupal sites today!