A backend engineer guide to Single Directory Components in Drupal

Single Directory Components completely changed how we handle the frontend. But if you spend most of your time engineering the backend, SDC can feel incredibly frustrating.

You build a massive render array, pass it to the template, and the strict schema rejects it instantly. The days of dumping raw entity objects into Twig are over.

When you work with SDC, the component dictates exactly what data it accepts. This guide details the cleanest way to format your data and bridge the gap between custom backend logic and strict frontend schemas.

Implementing the Component Workflow

If your backend architecture does not format data perfectly, the system throws a fatal error. Follow these steps to ensure your data matches the strict schema requirements.

1. Define your component schema

Every component needs a YAML file. This is the contract your backend must follow. Keep your properties simple and predictable.

name: Article Card
description: A strict component for displaying article summaries.
props:
  type: object
  required:
    - title
    - url
  properties:
    title:
      type: string
      title: Article Title
    url:
      type: string
      title: Target Link
    summary:
      type: string
      title: Teaser Text

2. Format the render array

Backend engineers usually try to pass the entire node object. Do not do that. Extract the exact strings your schema demands. Set the render array type to component so Drupal knows how to route it.

$build['article_card'] = [
  '#type' => 'component',
  '#component' => 'my_theme:article_card',
  '#props' => [
    'title' => $node->getTitle(),
    'url' => $node->toUrl()->toString(),
    'summary' => $node->get('field_summary')->value,
  ],
];

3. Render the component

Your Twig file is now incredibly clean. It only prints exactly what the backend provided. No complex logic. No processing overhead.

<div class="article-card">
  <h2><a href="{{ url }}">{{ title }}</a></h2>
  <p>{{ summary }}</p>
</div>

Notice how we completely avoid preprocess functions here. The template simply accepts the data contract and renders the output.

Key Considerations

Never pass full entity objects into SDC props. Always extract the raw values first.
Validate your schema early. A mismatched type will trigger a rendering error that brings down the page.
Keep your #props mapping clean by handling all complex business logic in the controller rather than the template.

This strict separation keeps your backend logic secure and your templates highly predictable. Adapting to Single Directory Components requires a mindset shift for backend developers. But it is the absolute best way to scale enterprise software without creating a massive technical debt trap for future engineers.

Drupal