Developers Guide to Building Modern WordPress Themes

Here’s a fun fact about the landscape of WordPress development: you can log in to 10 different WordPress sites and be greeted with 10 different editing experiences, each running a different theme, framework and development style. This situation is very unique to WordPress. There’s no other CMS that has this kind of diversity (or inconsistency, perhaps).

This is largely due to a not so fun fact, that there’s no established method for building a WordPress site. Yes, there are WordPress coding standards, but they’re meant to address the overall architecture and standards to the code itself. As far as what happens once you log in and how you manage your content within the WordPress dashboard, that process is up to the developer(s) and varies greatly from site to site. From page builders to the block editor, to completely hard-coded content (we’ve come across that more than you would think), it’s a bit of a roulette game when it comes to what is powering any given WordPress site.

When being tasked to build a new WordPress website, it can be overwhelming trying to find out which route is the best one, and the pros and cons of each option. That’s what this guide will attempt to help you with. Whether you’re a beginner or an experienced developer looking to expand their knowledge of WordPress’ capabilities, you should find something worthwhile here.

Guide Chapters:

• What are all the WordPress build types available?
• Tradeoffs of the different approaches
• How do I qualify a project for a certain build type?
• Developer Frameworks
• Pros and Cons Comparison
• Closing Thoughts

Overview of WordPress Build Types

WordPress builds fall into one of these four main buckets. Each has different capabilities, pros, and cons to their approach. How you determine which is the best build style is going to depend highly on the context of your individual client and project’s needs. We’re going to dig into each of these options, as well as do some comparing and contrasting to see what the strengths and weaknesses are of each. Note: This isn’t a comprehensive list of all the different options in each category!

*While frameworks aren’t technically a specific build type (as using them doesn’t preclude one from using something like the Classic or Block Editor), they change the WordPress development workflow substantially enough that they should be called out in their own category. More on that below.

Classic Themes

When WordPress was first getting its start, it was truly just a blogging tool. A mix of factors came together to make it more than that and soon it evolved to be used for just about any type of content management that people could throw at it. Writing custom WordPress themes began as a process of registering “post types” and creating “custom fields” to help organize and store different types of content. While it used to be the de facto way to build, with the advent of the block editor these types of themes are now referred to as “classic themes.”

– Native Post Meta / Custom Post Types

While not relegated only to classic themes, this is the core of how WordPress categorizes its content types. You can technically do all of this within the WordPress core functions, but it has its upper limits (e.g. you won’t find a way to create a “file upload” or a “repeater” field easily) and is fairly arduous. Thankfully, there are some well established extensions that helped standardize the process.

– Advanced Custom Fields (ACF) & Metabox (et al)

One of the most indispensable tools in the WordPress development process, classic themes leaned heavily on these custom field plugins, which allow developers to easily manage all the different custom data types that are needed for building out a content management system through an easy to use developer experience and user interface.

Block Editor

In December of 2018, WordPress went through a sea change, and unveiled a brand new editor called “Gutenberg,” which later evolved to be referred to as the “Block Editor.” It was a paradigm shift in WordPress content management and, subsequently, theme development. The major difference was now the editor was driven by JavaScript, React in particular, which annoyed a good many people (including me, at the time!). The other difference is that now all content types were organized as “Blocks.” Over time, as they worked out the bugs and the community embraced it more, Block Themes cropped up.

Three main ways to build out Block Editor themes:

– Block Themes / Full Site Editing (FSE)

FSE themes use WordPress’ block editor to construct the entire theme, including all global elements (e.g. header, footer, navigation, blog, etc..). They are more akin to the process one might experience when using Wix or SquareSpace, and are most often used for distributed themes.

– Hybrid Themes

Hybrid themes are basically what they sound like; a mix of the block editor and techniques retained from classic themes that allow developers to leverage the block editor without having to go down the route of Full Site Editing. This is our preferred way to build, as it allows us to curate the content management editing experience for clients without forcing them to feel like they need to manage every single facet of the site layout and design. The block editor experience can also be toggled on/off on selective parts of the site, in the event you have a type of content that doesn’t lend itself well to it (e.g. a post type with only a file upload field).

– Plugin Frameworks

The block editor on its own is fairly bare bones and doesn’t come with a lot of bells or whistles that you might find in other page builders like Elementor, or services like SquareSpace. For example, you won’t find any tools built into the editor that allow for custom attributes or styles for responsive/mobile layouts. Since its release, however, companies have tried to fill the gap and there’s quite a few to choose from. Some of the most popular examples would be Kadence Blocks or GeneratePress. These frameworks fill out the block editor functionality and introduce a whole host of features that would not otherwise be available, unless you chose to use the Block Editor APIs and customize it yourself, which is typically reserved for advanced developers. ACF Blocks is also a very popular option, as it allows users to write custom blocks without having to know advanced JavaScript or React.

Page Builders

These are not necessarily themes, but they effectively take over the WordPress editing experience in such a way that they need to be discussed as such. The most popular examples of Page Builders are Elementor, Beaver Builder and Divi. They also have their own themes that you can install and leverage, but these plugins can generally work with just about any theme out there. The end result is the same: the entire content management experience is a proprietary approach, and the editing experience is vastly different from one to another (nevertheless from other building methods).

Comprehensive Frameworks

WordPress can be an extremely open-ended platform, to the point where some solutions take over the WordPress experience to such a degree that they barely resemble WordPress any longer. These solutions tend to be all-inclusive and offer an end-to-end development process that is proprietary to that particular solution. Oxygen, for example, doesn’t even use the WordPress theme system at all, and instead introduces it’s own template hierarchy system.

Developer Frameworks

These frameworks, such as Sage and Timber, introduce an entirely different development workspace to the WordPress core, allowing developers to leverage PHP application frameworks like Laravel, or the Twig templating system. They can be used in conjunction with any of the aforementioned approaches, whether it’s native WordPress functionality or leveraging the Block Editor in some way or another. They are radical departures from “the WordPress way” of theme development, but still allow developers to benefit from WordPress’ most sought after features, which is arguably its intuitive dashboard and vast plugin ecosystem. We have more thoughts on this below.

Headless WordPress

A hot topic these days is the “headless CMS,” or in this case, Headless WordPress. This way to build is also known as Jamstack, and essentially decouples the WordPress backend/database from the front end presentation that the user interacts with. In other words, the backend content management can be done through WordPress, but the user-facing site can be deployed using something like NextJS. The main benefits with this method are performance, security, and the developer experience. Since the backend is hidden away, it’s unable to be compromised or subject to vulnerabilities and, since the frontend of the site is essentially a static HTML site, the performance metrics are very high as it means there are no database calls to slow down the site’s loading. It sounds great in theory, but this can have a lot of drawbacks, notably a steep technical setup and ongoing support. One of the bigger considerations is that plugins that clients might want to use will not work out of the box (if at all) with headless deployments, and that is often one of the main reasons that clients like to use WordPress in the first place!

Tradeoffs

This is probably a good time to mention what’s hopefully becoming obvious at this point: there is no perfect option. No matter what build approach is taken, there are always tradeoffs.

Take page builders for example; they offer incredibly high flexibility with the CMS that allows clients to create just about anything they had in mind, with little to no coding skills required. Why would you choose any other option? The flip side is those frameworks also come with high technical debt/overhead and vendor-lock in, meaning you’re at the whim and mercy of the plugin creators, whether it’s ongoing support, security updates, how they choose to set their pricing in the future, or worst case: the plugin goes away completely (which has happened!). Their proprietary nature can also make ongoing development and expansions harder than they would be for sites that don’t use them.

Here’s a poignant example: We had a past client who wanted to make a simple change of updating the colors on their site. Normally, that would be a quick job, but the original creator used the page builder without using any global settings or variables, which meant going through the site, module by module, and adjusting accordingly, turning what would be a 30 minute job into hours and hours of work. While that was a fairly extreme case, it highlights the risk when using platforms that deviate so heavily from standard development practices in exchange for the convenience of a “no code, drag n’ drop editor.”

In contrast, going with something like a Headless WordPress install will gain you incredible performance and security benefits, since you will be decoupling the frontend from the WordPress backend but that comes at a hefty price; technical complexity and required knowledge of Jamstack deployments. It also potentially limits the content management capabilities significantly, since you need to ensure the data you want to retrieve is able to be fetched through an API call. This could mean that if a future feature or plugin needs to be integrated, it could add up to significant development time compared to a standard WordPress instance.

These two charts can help visualize where these methods fall in relation to each other, and weighing the flexibility, coding skills, technical overhead/vendor lock-in, and ongoing support/development needed (which includes plugin updates and patch remediation):

Since our clients and projects want fairly high flexibility, but don’t want to be locked into a 3rd party plugin like a page builder and its associated technical overhead and performance issues, they prefer us to spend the time coding and building bespoke block editor sites. For us, that means hybrid themes are usually the sweet spot.

To see more about how these different build styles fit within this chart, reference the the pro/con list.

How to Decide on a Build Style

Some developers and agencies make this easy and simply stick to one approach, no matter what the project requirements are. This definitely simplifies the process, but runs the risk of picking a solution that won’t serve the project scope the best since you will always be adapting the client’s needs to fit within a framework. In our decades of experience, this can lead to awkward and clunky content editing experiences since you’re trying to cram the project scope into a predefined container. We choose not to stick to a specific method; we have a big toolbox and we feel there’s always a right tool for the job. To find the right tool, though, each project needs to be evaluated.

Whether you’re choosing an approach that you will apply to all projects, or on a per-project basis, there’s a set of criteria and some qualifying questions. First and foremost, what is your skill level? If you don’t know much about API integration, then attempting a headless install isn’t going to be a good time (unless you’re really ready to learn on the job quickly 😅). If you’re a highly skilled developer, something like a page builder will feel limited and rudimentary. We’ve developed a list of criteria over the years that we use to audit a project and make an informed decision:

Design Complexity

• Is the design going to require a lot of custom CSS to achieve, or is it simple enough where pre-existing components and grid building tools will suffice?
• Is there a lot of interactivity or animation, or is the design intended to be fairly static?
• Are the pages really diverse, or fairly consistently designed to a series of “templates?”

Content Management Needs

• Is the client expecting to have full control over the content and page layouts, or only needing select areas of the site to be editable?
• Are they technically savvy and able to navigate a robust CMS, or do they need a lot of guidance and guardrails?
• Do they plan on adding new sections and pages that might not be included in the original design scope (e.g. marketing landing pages or squeeze pages)?

Features and Functionality

• What integrations are wanted besides content? For example: Events Calendars, Membership Portals, User Forms, Portfolios, Product/Document databases.
• Are there going to be any 3rd party application integrations (e.g. API feeds or interactivity with other apps)?
• Are there any custom content editor/permissions needs?

Performance & Security

• How important is security to the client/project?
• How important is high performing SEO rankings and SEO management?
• What kind of hosting will be available to use?

Ongoing Support & Maintenance

• Will the site receive regular monitoring and updates?
• How many plugins will be needed?
• Will there be a defined development deployment process (e.g. a CI/CD or something similar)?

Budget & Timeline

• This isn’t a technical criteria, but it’s still a factor. For us, custom hybrid, blocks and headless tend to simply take more time and cost more money, whereas a site in Beaver Builder can be turned around in comparatively short order (although often with some functionality and design sacrifices).

In this grid we’ve rated each option. Higher stars means it excels in that category, whereas lower stars means there are concerns or considerations with this build style in that area, for one reason or another.

	Design Accuracy	CMS Flexibility	Security Rating	Performance Rating	Support Rating	Ease of Coding
Classic Theme
Blocks Theme
Hybrid Theme
Headless WP
Page Builder

Note: This table is an approximation based off of personal experience and meant to demonstrate strengths and weaknesses at a glance. For example, classic themes have a two star security rating since they often need a number of plugins to function well (and numerous plugins can lead to hacks). Page builders have a low design accuracy rating because despite their flexible editing capabilities, they can also prevent a lot of custom requests which often requires jumping through a lot of extra hoops to do things that would otherwise be simple through code.

A note on Developer Frameworks

Libraries like Sage and Timber are fairly divisive in the WordPress community, and we feel deserve a separate mention. Using a framework like Sage proposes a similar notion for the development workflow that page builders present for content editing; it will replace “the WordPress way” with its own proprietary process. Sage in particular takes the Hybrid Theme approach, but leans on Laravel’s Blade templating system, along with various package and dependency managers. They are marvelous technical feats, and bring modern PHP templating and JavaScript tooling to WordPress theme development, but they’re not without their tradeoffs, as well:

• They add a significant abstraction layer on top of an existing piece of software. In a way, that is the point of them, but Murphy’s Law is an ever-present consideration (in other words: more things to go wrong)
• Some plugins don’t play well with them and will require extra work to make stable. It’s a short list currently, but something could be released in the future that isn’t compatible, so it’s best to go in eyes wide open
• Site and dependency upgrades can cause ongoing headaches (e.g. Sage 8 -> 10 was a big jump and introduced some breaking changes)
• They shine when used for larger applications, but can be overkill for many of the smaller to medium sized projects that we’ve seen them get used on
• They presume future developers who might inherit the site will want to continue to use them. It’s not something you can simply turn off or migrate away from without a rewrite, and if you’re producing applications for clients that you will hand off control to, it’s nice of you to think about who might inherit your work! If it’s an internal project that will be managed by a development department/team, this is less of a consideration, of course.

Laravel and Blade are amazing platforms to build with, but whether they should be inserted into the WordPress ecosystem is a divisive opinion in the community. We don’t personally use these frameworks, as its our position that if there’s a large enough project to substantiate the use of something like Sage, then there’s likely a better platform than WordPress that would be a better fit, anyway. That is just our opinion and this guide is here to demonstrate that there’s no “right” or “wrong” way to build, but choosing what works best for you (and for the project/client!).

Pros and Cons Recap

Who doesn’t love a good pro/con and TL;DR? 🙂

Closing Thoughts

Even though this seems like a lot to consider, you shouldn’t obsess too much about whether you’re picking the “perfect” build type because there will always be tradeoffs no matter which route you choose. Beginners will naturally gravitate to more “turn-key” options like page builders or all-inclusive frameworks, while more skilled developers tend to be drawn to hybrid themes, headless, and developer frameworks like Sage.

And, while there might be a personal preference, the project might demand otherwise. There have been instances where we’ve thought that Beaver Builder was going to be the best choice, even though we would have much preferred to write a hybrid theme. We’ve even been asked to write a classic theme with no modularity because the client didn’t want staff to be able to make any content or layout changes without approval.

The goal, hopefully, is to find the best option for the project, and while WordPress’ ecosystem seems rather chaotic in terms of options and variability, the upshot is that no matter what your project demands, there is very likely a WordPress solution that will fit the bill.