Smarter Theming: Single Directory Components in Drupal

Single Directory Components (SDC) is a new approach to building user interfaces in Drupal, introduced as an experimental module in Drupal core 10.1 and now fully released in Drupal 11 and DrupalCMS (coming January 15, 2024). It provides a standardized method for creating reusable UI components, aiming to address challenges with finding assets, scattered file systems, and lack of clear data expectations in traditional Drupal theming. SDC seeks to align Drupal with modern front-end development practices using a component-based architecture. 

Links to Drupal.org documentation:
https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components /quickstart 

https://www.drupal.org/docs/develop/theming-drupal/using-single-directory-components 

Quick Introduction to SDC:

Key Concepts

The Problem SDC Solves:

• Scattered Assets: Traditional Drupal theming often results in CSS, JavaScript, and Twig templates being spread across different folders, making it difficult to track down the code affecting a particular UI element and it's really easy to lose context.
   
• Unknown Data: It's hard to determine what data is expected by a template and how to manipulate it, often requiring turning on twig debugging mode and dump the entire context of the template file and then start looking at it and try to figure out what the heck any of these variables mean.
   
• Lack of Reusability: While Twig templates could be included and embedded, there wasn't a clear concept of a component in Drupal with standardized metadata and structure.
   
• Inconsistent Theming: Previous to SDC there were many different ways that you could define components depending on which agency you worked for and what they decided was the right way to do it.
   
• Barriers to Entry: Drupal's theming system could be difficult for new front-end developers to grasp, deterring wider adoption. Sometimes finding out where the assets are located is difficult, making Drupal adoption more difficult.

Core Principles of SDC:

• Single Directory: All files associated with a component (Twig template, CSS, JavaScript, metadata) reside within a single directory, making components easy to locate and manage. Everything has to be in that directory... when you are editing your components you know where to go and you know where to find the everything that's affecting that particular piece of your of your website.
   
• Reusability: Components are designed to be reusable building blocks for UI development. Components are sort of like this mythical box of Legos that you can click together to build your user interface.
   
• Standardization: SDC introduces standardized definitions for components through metadata files.
   
• No External Hooks: SDC templates exclude Drupal's preprocessing and hook systems, ensuring no external impacts on the rendering of components and preventing unexpected behaviors. No module will ever change how your component is rendering because there's no way for it to really interact with the rendering process for an SDC.
   
• Component Definition: Components are defined by their name, metadata, template, styles, and scripts. 
  The component.yml file contains data about its purpose and its inputs.
   
• Automatic Asset Handling: Drupal automatically creates asset libraries for components, loading CSS and JavaScript only when the component is used. You just put the right files in the right place and Drupal will do the rest so it will be loading only the CSS and JavaScript libraries that it needs to render that component.
   
• Metadata for Clarity: Metadata in component.yml files helps ensure that the inputs are well documented allowing for clarity and documentation about the data structure of each component.

Component Structure:

• Directory Structure: A component's files are all kept in a single directory within a "components" folder at the root of a module or theme. These component directories can be nested. You can create any type of arbitrary nested directory structure and it'll scan the structure and find them.
   
• Component Files:
  • [component_name].component.yml: Contains component metadata (name, description, status, properties, slots).
  • [component_name].twig: Twig template for rendering the component's markup.
  • [component_name].css: CSS for styling the component.
  • [component_name].js: JavaScript for the component's interactivity.
  • Other optional assets like images, fonts can be included.
     
• Metadata (.component.yml):
  • name: Human-readable name of the component.
  • description: Description of what the component does.
  • status: Lifecycle status (stable, experimental, obsolete).
  • props: Defines data inputs for a component, including their types and validation schema (using JSON Schema). Props are data that is input into a component where the structure of the data is well known.
  • slots: Defines placeholder regions (blocks) where additional content can be embedded, without requiring to know the structure of that data.
  • library_overrides: Allows modification of the automatically generated asset libraries.
  • replaces: Allows a theme to completely replace a component from another module or theme.

Using Components

• Twig Inclusion: Components are used via Twig's include or embed syntax in other templates using the component's namespace (module/theme name + component name), e.g., aloe_vera:chip or sdc_examples:chip.
   
• Render Arrays: Components can also be used through render arrays, specifying the component name and passing properties or slots as needed.
   
• Validation: SDC is capable of validating the data inputs according to schema, allowing errors to be reported during development when a component is used incorrectly - for instance, if you are passing a non-email address into a property that expects an email address.
   
• Component Replacement: A theme can replace an existing component by copying the component directory, modifying it, and adding the replaces property to the metadata file. 

Benefits of SDC:

• Improved Maintainability: Clear separation of component code, making it easier to manage and refactor. For instance, with a component, since that style only applies to that particular component, you know that you can refactor it and you can delete it if you need.
   
• Enhanced Reusability: Encourages component-based design, promoting the use of common UI elements across a site.
   
• Better Developer Experience: Makes it easier for front-end developers to work with Drupal, particularly those familiar with component-based frameworks like React or Vue. 
   
• Performance Gains: SDC automatically handles loading assets only when they are needed.
   
• Integration with Other Tools: SDC facilitates integration with design and development tools like Storybook, Figma, and Fractal. 
   
• Consistent Methodology: Provides a single and consistent way for all developers on a Drupal site to use components. If the Drupal community coalesces around a single way of solving this problem it would become available to more people to use and it would benefit integration with Drupal and all of the other Drupal tools.

Future of SDC:

• Transition to Stable Core Feature: SDC is an experimental module in Drupal 10.x but already in Drupal 11 and Drupal CMS.
   
• Component Integration with Drupal Features: SDC may be integrated with other Drupal features such as Layout Builder and Views and will be central to the upcoming Experience Builder, coming to Drupal CMS later in 2025.
   
• Broader Adoption: SDC is expected to become the standard way to create reusable components in Drupal.
   
• Component Sharing: The possibility of creating a centralized component repository, similar to the Drupal module system is being discussed by the Drupal Core team and other stakeholders.
   
• Integration with Design Systems: SDC is poised to play a crucial role in building and implementing design systems within Drupal.

SDC and USWDS (US Web Design System)

• The US Web Design System (USWDS) is a design system that aims for a consistent and accessible government web presence.
   
• SDC facilitates the integration of USWDS components into Drupal sites.
   
• Challenges in adapting USWDS, such as its monolithic CSS structure and SAS-based design tokens, are being addressed by SDC.
   
• Projects like "The Governor" theme are exploring ways to split USWDS into individual components and leverage SDC for easier maintenance and better performance.

Key Takeaways

• SDC marks a significant shift in Drupal's theming approach by introducing a standardized, component-based architecture.
   
• SDC addresses long-standing challenges with asset management, data clarity, and reusability in Drupal themes.
   
• It aims to improve the developer experience by aligning Drupal theming with modern front-end development practices.
   
• The metadata system allows for a data contract and validation of component inputs which allows other tools to better represent the intent of a component.
   
• SDC has the potential to become a core part of how Drupal handles UI development.
   
• SDC is in Core in Drupal 11!
   
• The SDC module is aiming for standardization and is still looking to address a variety of edge-case scenarios.

Video Resources: