What's the Best Way to Build Modular WordPress Themes ?

At fjorge, we version control our projects with git. The power that gives us to merge and manage code across teams of developers is an essential part of our workflow. As our team has grown and we've honed our processes, we've come up with some practices that help reduce merge conflicts as well as making our projects easier to maintain and extend. For WordPress projects, we've moved towards creating blocks that can be added to page templates instead of creating self-contained page templates. This makes page templates more flexible, makes future development easier and gives clients the ability to create pages from any combination of blocks.

We use Advanced Custom Fields' flexible content layouts to configure the blocks in WordPress. Then the part that reduces merge conflicts and keeps our code easy to maintain is how we organize our themes. Each flexible content layout must have its own template part that gets called by looping through the ACF flexible content field. We usually put this loop in a separate template part that can be called from any page template (called something like blocks.php). What this means is that most of our development happens in modular template parts. For example, a developer creating a block for displaying forms would make a new template part called blocks-form.php and put all of her code there. Then that template part gets added to the list of flexible content layouts in blocks.php. The only potential merge conflict this creates is if another developer has also added a layout to the list in blocks.php and all that has to be done to resolve the conflict is to keep both changes. We do the same thing with styles by creating a sass file for each block that gets called from the main stylesheet which ends up being just a list of sass files to include. We've recently set up one of our starter themes to combine separate javascript files as well and are testing out the new structure on a couple projects.

For more info on ACF flexible content fields, read the documentation here. Since all good development requires good design, there's a good overview of modular design presented in this article from A List Apart by Alla Kholmatova, "The Language of Modular Design".