Single Directory Components and the shape of Drupal theming

Single Directory Components arrived in Drupal 9.3 as a quiet, easy-to-miss change. You could now put a component — the Twig template, the schema, the CSS, the JavaScript — in a single folder. Drupal would autodiscover it. You would not need to register it in theme.yml. You would not need to write a preprocess function.

It sounds like convenience, and it is. But the real change is architectural. Single Directory Components move the boundary between “what a component is” and “how a component integrates,” and that shift rewires how theming teams and component teams actually work.

What changed

In traditional Drupal theming, a component is multiple artifacts. The template lives in templates/. The Sass lives in scss/. If there is JavaScript, it lives somewhere else. The configuration that tells Drupal about the component lives in theme.yml. You integrate it by writing a preprocess function. If the component needs data to work, you fetch it in the preprocess, transform it, and pass it to the template.

This works, and I have built production themes this way. It also scatters decisions. The shape of a component lives in three places. The contract between Drupal and a component (what data it needs, what it outputs) is implicit — documented in prose or not at all.

Single Directory Components change this: a component is a folder. The folder contains the template and a component.yml file that declares the schema — what props the component receives, what they are shaped like, what they default to. Everything a stranger needs to understand a component is in that folder.

The consequences ripple outward. You no longer need a preprocess function for every component. The schema replaces it. A component knows what data it needs — it stops being the preprocess function’s job to guess. Developers can now look at a component folder and understand its contract without reading code. Tooling can inspect that contract without parsing Twig.

Why this matters for teams

In a traditional Drupal theme, the preprocess layer is where implicit knowledge lives. That is where the conventions are: “fetch the node, use the published date as the timestamp,” or “truncate excerpts to 150 characters.” New developers learn it by reading code. You document it in a readme that falls out of date.

In an SDC theme, that knowledge is explicit in the schema. A card component with props for title, excerpt, and timestamp is self-documenting. The component is announcing: “I need this data in this shape.” A team member can look at the schema and understand the contract. A bot can lint against it. Drupal can warn you at render time if you try to pass the wrong type.

This shifts who controls the theming conversation. In traditional Drupal themes, the person who understands the preprocess layer is the gatekeeper. In SDC themes, anyone who can read YAML can understand a component’s contract. That is a smaller skill barrier for a multisite platform where five teams are building on shared components.

It also changes how you think about integration. If a component’s props are declared in the schema, then the job of integrating it into the rest of Drupal becomes a mapping problem: “where does the title come from? The node title. Fetch it. Pass it as the title prop.” That mapping can happen in a preprocess function, in a view controller, or in Twig itself. The choice is clearer because the component itself has become simpler.

What I think happens next

Single Directory Components are still finding their foothold in themes. Many production themes have not migrated yet. Many are still using a mix of SDC and traditional components. That is fine — they coexist. What interests me is what happens when an entire theme is built ground-up as SDC.

I think the shape changes in two ways. First, themes get smaller. A component that knows its own contract does not need five lines of preprocess function. A theme that is fifty SDC components is leaner than one that is fifty traditional components with preprocess logic.

Second, I think components start to cluster differently. In traditional themes, components cluster by where they appear: hero, card, footer. In SDC themes, components cluster by what they do: all things that display a person, all things that display a date, all things that handle navigation. Because the schema is explicit, you can reason about what fits together.

The strongest counter-argument is that this is fine for a well-structured component library but falls apart with institutional variation. A medical school’s component for displaying faculty might need fields that a business school’s does not. Single Directory Components make that explicit — the schema declares the mismatch — but they do not solve it. You either have one component that covers both use cases (and gets complex) or separate components per institution (and lose the benefit of sharing).

I think that is a real tension, and I do not think it is solved yet. What I am watching is whether the Drupal community settles on a pattern for multisite SDC libraries, where variation is sanctioned through configuration rather than through schema inflation. That is the thing that would shift SDC from “a cleaner way to build themes” to “a fundamentally different way to do theming at scale.”

If you are building a multisite SDC library and have found a pattern that holds up, I would genuinely like to see it.