Single Directory Components (SDC) in Drupal 10

Try to imagine there is a way to make website UI components perfectly organized, easily reusable across projects, consistent throughout web pages, and more. Yepp. It's all about Single Directory Components (SDC)! A fresh way of theming introduced in Drupal 10.1, makes all of this possible.

Single Directory Components (SDC) are Drupal core’s approach to implementing components. In SDC, all the files needed to render a component are organized into a single directory, which is why it's named that way. This directory includes Twig, YAML, and optionally CSS, JavaScript, and other files. When the template is used, SDC will automatically generate a library to load the CSS and JavaScript.

Here are the general key points of Single Directory Components (SDC) in Drupal:

1. Unified Structure: All related files for a component (CSS, JavaScript, templates, configuration) are grouped in a single directory.
2. Improved Maintainability: Simplifies updates and debugging by keeping all component files together.
3. Consistency: Promotes a standardized and organized structure for components across the project.
4. Enhanced Reusability: Makes it easier to reuse components across different projects or parts of a project.
5. Better Organization: A well-organized directory structure helps developers quickly find and work with the files they need, boosting productivity and reducing errors.

These points highlight the advantages and the structured approach that SDC brings to Drupal development.

First of all, you’ll need to use a Drupal 10.1 core version or later. There are a few preparation steps before you can start creating a new component and here they are:

1. Enable the Single Directory Components module on the Extend tab in the Core (Experimental) section. Since Drupal 10.3 it will have a stable release.

2. Disable CSS and JS aggregation on the Configuration > Development > Performance page of the Drupal admin UI for development purposes.
3. Enable Twig development mode and disable caching. Starting with Drupal 10.1, you can do this on the new “Development settings” page at Configuration > Development

Let's go through the steps of creating a new component:

1. Create the components directory in the root of your custom theme or module’s directory.
2. In the components directory create a new directory with the name of your component. For instance "my-component". The structure will be "components/my-component"
3. Create two required files
   1. my-component.component.yml - this contains the definition of the component including name, status, schema, etc
   2.  my-component.twig - contains the markup with the name of your component. Note that the file extension should be .twig, not .html.twig, as is common in other theme template files.
4. Optionally you can add CSS, JavaScript, source files (Sass, etc), images, etc.

Follow the link to learn more about these example components for more details.

The overall structure of the component should look like this

|- my-theme
    |- components
        |- my-component
            |- my-component.twig (required)
            |- my-component.component.yml (required)
            |- README.md
            |- thumbnail.png
            |- my-component.js
            |- my-component.css
            |- assets
                |- img1.png

As an example, I've created a components directory with the necessary blog component.

There are two variants of render components:

1. Use include()

Use the Twig `include()` function when there are no slots or arbitrary HTML properties, and the data follows a defined structure.

Copy the twig markup template from the default node.html.twig file and paste it into the blog.twig file. In the original node--blog.twig.html file remove the twig markup and use {% include "my_theme:blog" %} instead of it.

And that's it actually. Here is what we see in the twig debug of the node without using SDC

and what we get in the result of using SDC

SDC places emoji at the beginning and end of the component to make it easier to locate.

Also, you can render the necessary fields inside component easily. In the node--blog.html.twig include a component with blog_title, blog_body, and blog_cta

Then we need to render it in the component

Read more about include() in the Twig documentation.

1. Use {% embed %}:

Use a Twig {% embed %} tag if you need to populate slots.

Example of how to pass in a slot (Twig block) in a card component:

{% embed 'sdc_examples:my-card' with { header: label } %} 
  {% block card_body %}
    {{ content.field_media_image }} 
    {{ content|without('field_media_image') }} 
    {{ include('sdc_examples:my-button', { text: 'Like', iconType: 'like' }, with_context = false) }} 
  {% endblock %} 
{% endembed %}

Read more about embed in the Twig documentation.

One of the best features of using SDC, in my opinion, is adding CSS, Javascript, etc without declaring the library. For the CSS and JavaScript to load automatically, they must be named after the component (e.g., `my-component.css` and `my-component.js`). It's awesome!

Single Directory Components (SDC) is a cool feature to organize your code and make it understandable and easy to manage. By grouping all necessary files—such as templates, CSS, JavaScript, and YAML configuration—into a single directory, SDC enhances maintainability, reusability, and consistency across projects. I'm happy to see Drupal implementing more and more new features to improve the developer experience.

1. Single Directory Components on Drupal.org
2. Example components
3. Single Directory Components in Core: Pittsburgh 2023
4. WTF is SDC in Drupal?