Building Single Directory Components in WordPress: A Modern Approach to Modular Theme Development

For years, WordPress theming has revolved around sprawling directories of templates, partials, stylesheets, and functions. While that model has served the community well, modern development practices—especially those inspired by component-based systems like React, Vue, and other modular frameworks—have reshaped how teams think about reusability and maintainability.

Enter Single Directory Components (SDCs): a new approach to WordPress theme architecture that brings modular organization, better scalability, and a smoother editorial experience. Introduced in recent WordPress versions, SDCs allow developers to package templates, styles, scripts, and metadata together in one folder. This creates self-contained building blocks that make your themes easier to manage—and your content more consistent.

In this article, we’ll explore how to build Single Directory Components in WordPress, step-by-step. We’ll cover setup, implementation, best practices, and how this technique improves both developer and editor workflows.

1. What Are Single Directory Components?

Single Directory Components are a way to group all the assets for a specific component—its PHP template, CSS, JavaScript, and JSON metadata—within a single directory. Rather than scattering these files across multiple folders, everything a component needs lives in one place.

For example, imagine a simple “Card” component used across your site. Traditionally, you might have:

/templates/parts/card.php
/assets/css/components/card.css
/assets/js/components/card.js

With SDCs, those files are now encapsulated:

/components/card/
 
├── card.php
 
├── block.json
 
├── card.css
 
└── card.js

This seemingly small change has a huge impact on scalability. Each component is now self-contained, portable, and easier to version or reuse in other projects.

2. Why This Matters for WordPress Development

As WordPress moves toward a full-site editing (FSE) paradigm, it’s increasingly important to align theme structures with modular, reusable design patterns. Single Directory Components help bridge the gap between traditional PHP-based theming and block-driven design systems.

For developers, this means:

• Cleaner project organization.
• Easier onboarding for new team members.
• Reduced code duplication.
• The ability to build and maintain a design system directly in WordPress.

For content editors, the benefits are equally powerful:

• Pre-styled, reusable components available in the block editor.
• Greater visual consistency across pages.
• Less reliance on developer intervention for layout or design tweaks.

3. Setting Up Your Environment

Before diving into SDCs, make sure your environment is ready.

Requirements:

• WordPress 6.3 or later.
• A block theme or hybrid theme structure.
• PHP 7.4+ recommended.

You’ll also want to confirm that your theme supports block registration and JSON-based configuration via theme.json. For the purpose of clarity in this tutorial, we’ll be using the ACF Pro plugin to register our block. The SDC structure can be adjusted to support any method of custom block registration.

Enabling component support:

Most modern block themes support SDCs out of the box, but it’s good practice to structure your theme with a dedicated /components/ directory for clarity. Within that folder, you can start defining your custom components.

4. Creating Your First Single Directory Component

Let’s walk through an example: building a Card component that displays an image, title, and description.

Step 1: Create the directory structure

Inside your theme, create a folder at:

/wp-content/themes/your-theme/components/card/

Step 2: Define the component metadata

Every component needs a block.json file to define its properties and integration with WordPress. Different block registration methods will require different json structure. This example uses the structure required for ACF Pro block registration.

Example:

{
  "name": "your-theme/card",
 
  "title": "Card",
 
  "description": "A reusable card component for content teasers.",
 
  "category": "design",
 
  "style": "file:./card.css",
  "editorStyle": "file:./card.css",
  "viewScript": "file:./card.js",
  "editorScript": "file:./card.js",
  "acf": {
    "renderTemplate": "card.php"
  },
 
  "supports": {
    "html": false
  },
 
  "attributes": {
    "title": {
      "type": "string",
 
      "default": "Card Title"
    },
 
    "text": {
      "type": "string",
 
      "default": "This is a sample card description."
    },
 
    "image": {
      "type": "string"
    }
  }
}

This file tells WordPress how to register the component as a block, how to render it, and what assets to include.

Step 3: Create the template

In card.php, define how the component should render:

<div class="card">
 
<?php if (!empty($attributes['image'])): ?>
 
<img src="<?php echo esc_url($attributes['image']); ?>" alt="">
 
<?php endif; ?>
 
<h3><?php echo esc_html($attributes['title']); ?></h3>
 
<p><?php echo esc_html($attributes['text']); ?></p>
 
</div>

Step 4: Add styles and scripts

In card.css, define your styles:

.card {
 
  border: 1px solid #ddd;

  border-radius: 8px;
 
  padding: 1rem;
 
  background: #fff;

}
 
.card img {
 
  max-width: 100%;
 
  border-radius: 4px;
 
}

If needed, card.js can add interactivity—like hover animations or dynamic behavior.

Step 5: Register the component

Register your block using the register_block_type() function. It’s important to adjust the file path for your block to reflect the new SDC structure. The following example can be placed in the theme’s functions.php file to register the block.json data added to the card component’s directory. Once you’ve added your files, refresh the Block Editor and search for “Card”—your new block should appear, ready for use.

5. Best Practices for Scalable Component Systems

Building with SDCs opens the door to a more maintainable theme architecture, but scaling this approach requires thoughtful practices:

1. Use consistent naming conventions.

Stick to lowercase, hyphenated names (e.g., hero-banner, testimonial-grid) for clarity.

2. Leverage design tokens.

Centralize colors, typography, and spacing in theme.json so your components inherit consistent values.

3. Keep logic minimal.

Components should focus on rendering and presentation. Business logic should live elsewhere.

4. Document everything.

Maintain a README.md inside each component folder describing usage, attributes, and dependencies. This ensures new team members can quickly understand how to use and extend components.

5. Plan for reusability.

Design components that can adapt to different contexts with flexible attributes, rather than hard-coded assumptions.

6. Common Pitfalls and Troubleshooting

Even seasoned developers can run into roadblocks when adopting SDCs. Here are a few common issues—and how to avoid them.

Problem: Styles not loading.

Fix: Make sure style in your component’s JSON file points to the correct relative path (e.g., "file:./card.css").

Problem: Block not appearing in the editor.

Fix: Check that your component’s name property is unique and properly namespaced (e.g., "your-theme/card").

Problem: JavaScript not executing.

Fix: Confirm your script path is correct and ensure it’s enqueued properly via the JSON definition.

Problem: Conflicts between components.

Fix: Use component-level class naming (.card, .hero-banner) to isolate styles and prevent global overrides.

7. How Single Directory Components Empower Content Editors

The shift to SDCs doesn’t just benefit developers—it transforms how editors work inside the WordPress Block Editor.

• Reusable visual patterns: Editors can add pre-designed blocks like “Card,” “Hero,” or “Quote” without needing to touch code.
• Consistent branding: Since each component is styled and structured by developers, editors can focus purely on content.
• Fewer regressions: Updates to a component automatically apply site-wide, maintaining design integrity without rework.

This creates a tighter collaboration loop between design, development, and editorial teams—one of the hallmarks of modern digital governance.

8. Conclusion: A Step Toward Modern WordPress Architecture

Single Directory Components represent more than just a cleaner folder structure—they’re a step toward a fully modular, scalable WordPress architecture. By encapsulating templates, assets, and metadata, developers can deliver consistent, reusable design systems while empowering editors with flexible yet controlled content options.

For teams that manage large or complex WordPress sites—such as higher education institutions, nonprofits, and government agencies—this approach dramatically simplifies theme maintenance and improves long-term sustainability.

If you’re exploring ways to modernize your WordPress theme architecture, consider adopting Single Directory Components as part of your next project.

Ready to evolve your WordPress workflow?

Aten’s team of WordPress and Drupal experts can help you design a component-driven architecture that empowers editors and scales with your organization’s needs.

Contact us to learn more.