Hello, everyone! I’ve embarked on an exciting journey to implement a new design for a large e-commerce project. This project involves integration with Laravel, and in the future, there’s even the possibility of incorporating ReactJS where necessary. Starting with the theme structure, I revisited a long-standing idea I’ve wanted to explore and discuss in detail. This post marks the beginning of a series on this topic, so let’s dive in!
When the Standard Isn’t Enough
I often found myself constrained by the Underscores (_s) theme framework from Automattic. While it’s a WordPress industry standard, designed with robust best practices in mind, I felt something was missing-especially after working extensively with modern technologies like ReactJS, Laravel, Composer, and beyond.
These experiences have expanded my horizons, making it difficult to stay limited to traditional approaches. While Underscores remains an excellent foundation for building WordPress projects, I feel it could benefit from a significant update. For instance, I’ve noticed deprecated Node packages in its dependencies, which could be problematic for modern workflows.
Sure, there’s Sage by Roots.io – a fantastic framework for modern WordPress development that leverages Laravel, Composer, and Blade templates. However, my experience with Sage sometimes required additional debugging and setup time, adding unnecessary complexity to my workflow. This sentiment is echoed in some community discussions, as seen here:
It’s a great tool, but not always suitable for a team where maintenance might fall to a WordPress developer unfamiliar with Laravel or Blade. For my needs, Sage sometimes adds too much complexity, especially for quick maintenance or handoffs to developers unfamiliar with its architecture.
Crafting a Modern WordPress Theme Structure
Through extensive research and hands-on experimentation, I’ve developed a theme structure that aligns with modern web development practices. This approach prioritizes modular design, organized SCSS architecture, and a clear separation of concerns, ensuring both maintainability and scalability for future growth.
Key Features of the Structure:
- Modular Design: Template parts and SCSS are divided into logical components for better maintainability.
- SCSS Organization: Adheres to the 7-1 architecture, with dedicated folders for components, layouts, and utilities.
- Reusability: Custom PHP components and template parts are designed for easy reuse across the theme.
- Modern Build Tools: Integrates tools like Gulp or Webpack for asset optimization, including SCSS compilation and CSS/JS minification.
- WooCommerce Compatibility: A specialized folder is included for overriding WooCommerce templates.
- Translation Ready: A
languagesfolder ensures seamless integration with multilingual plugins like WPML or Loco Translate.
This structure is tailored for scalability and efficient development while maintaining compliance with WordPress standards.
Exploring Key Concepts: Components, Partials, and Template Parts
A recurring question is: why do we need partials, components, and template-parts? Let me break it down:
Partials
- Purpose: Small, reusable PHP templates for non-visual or logic-driven elements.
- Examples:
- breadcrumbs.php
- pagination.php
- meta.php
- Why Use Them?
- Lightweight and focused on outputting data or logic.
- Easily reusable across layouts without additional styling or scripts.
Components
- Purpose: Modular, self-contained UI blocks bundling HTML, CSS, and JavaScript.
- Examples:
- Button (components/button/)
- Navigation menu (components/navigation/)
- Why Use Them?
- Encapsulation ensures consistency and maintainability.
- Flexible for use in multiple layouts and contexts.
Template Parts
- Purpose: Larger, WordPress-specific layout sections like headers, footers, or content blocks.
- Examples:
- template-parts/content/content-single.php
- template-parts/header/header-main.php
- Why Use Them?
- Organize and manage layout sections tied to WordPress template hierarchy.
Comparison: Template Parts vs Components vs Partials
| Aspect | Template-Parts | Components | Partials |
|---|---|---|---|
| Purpose | Layout sections (headers, footers, content). | Modular UI blocks (buttons, menus). | Reusable non-UI or logic-driven elements. |
| Scope | Tied to WordPress templates. | Independent, reusable UI. | Smaller, PHP-driven code fragments. |
| Usage | Called via get_template_part(). | Included directly in templates. | Injected into larger templates. |
| Structure | Focuses on PHP/HTML structure. | Encapsulates HTML, CSS, JS. | Minimal, logic-based. |
Comparison: Template Parts vs Partials
| Aspect | Template-Parts | Partials |
|---|---|---|
| Purpose | Represents sections of a layout. | Reusable code fragments. |
| Scope | Broader, tied to template hierarchy. | Smaller, non-visual logic. |
| Examples | Header, footer, content sections. | Metadata, breadcrumbs, pagination. |
By maintaining a distinction between these three concepts, you can keep your theme structured, maintainable, and adaptable for future needs.
Should You Add a src Folder?
Including a src folder for development files (like raw SCSS and unprocessed JS) is a modern best practice.
Benefits of a src Folder
| Benefit | Description |
|---|---|
| Separation of Concerns | Keeps raw source files separate from production-ready assets. |
| Improved Organization | Groups all development files into a clear, central directory. |
| Streamlined Workflow | Build tools process and optimize assets into production-ready files. |
| Collaboration-Friendly | Prevents accidental edits to compiled files and reduces version control clutter. |
Adding a src folder is particularly beneficial if you:
- Use build tools like Webpack or Gulp.
- Anticipate frequent updates or modular development.
- Want a clear distinction between development and production files.
Here’s how it’s my structure looks:
/theme ├── assets/ # Processed and ready-to-use assets │ ├── css/ # Compiled CSS files │ ├── js/ # Minified JavaScript files │ ├── fonts/ # Web fonts (e.g., WOFF, TTF, etc.) │ ├── img/ # Optimized theme images │ └── vendors/ # Third-party libraries (e.g., Bootstrap, jQuery plugins) ├── src/ # Source files (for development purposes) │ ├── scss/ # SCSS source files for styling │ ├── js/ # JavaScript modules or raw scripts │ ├── fonts/ # Unoptimized web fonts │ ├── img/ # Raw/unoptimized images │ └── components/ # Component-specific source files ├── components/ # Reusable UI components │ ├── button/ │ │ ├── button.php │ │ └── assets/ # Component-specific assets (JS, SCSS, etc.) │ ├── header/ │ │ ├── header.php │ │ └── assets/ │ └── navigation/ │ ├── nav.php │ └── assets/ ├── inc/ # Core PHP functionality │ ├── classes/ # Autoloaded PHP classes │ │ ├── Class-Example.php │ │ └── Class-Other.php │ ├── env.php # Environment-specific data │ ├── custom-post-types.php │ ├── enqueue-assets.php │ ├── theme-setup.php │ └── helpers.php ├── layouts/ # Layout templates for flexible structure │ ├── full-width.php │ ├── sidebar-left.php │ └── contact.php ├── template-parts/ # Content-related template parts │ ├── content/ │ │ ├── content-page.php │ │ ├── content-single.php │ │ └── content-excerpt.php │ └── header/ │ ├── header-main.php │ ├── header-top.php │ └── header-mobile.php ├── woocommerce/ # WooCommerce templates │ ├── archive-product.php │ ├── content-product.php │ └── single-product.php ├── partials/ # Common PHP includes for non-UI elements │ ├── breadcrumbs.php │ ├── pagination.php │ └── meta.php ├── 404.php ├── footer.php ├── functions.php ├── header.php ├── index.php ├── style.css └── single.php
A Journey in Progress
This is a work in progress, and I’ll continue to refine and improve the structure as I gain more insights and feedback. I plan to share updates and dive deeper into practical examples in future posts.
If you have thoughts, suggestions, or questions, I’d love to hear them! Feel free to leave comments below—your input is invaluable in shaping the evolution of this approach. Together, we can foster a constructive discussion and explore better solutions for WordPress theme development.pic!
Final Thoughts and Inspirations
This approach represents my journey toward a modern WordPress theme structure optimized for maintainability, scalability, and contemporary development practices. I’ll continue refining this structure as I gather feedback and insights.
For further exploration, I recommend checking out:
Stay tuned for more posts in this series, where I’ll dive deeper into practical examples and challenges I encounter along the way.
Happy coding! 🚀