Why is WordPress development painful?

When I started as a web developer four years ago, I'd frequently hear more experienced software engineers discuss their mutual dislike for WordPress.

I never understood why they disliked it–I thought WordPress was great! It came with an admin interface, authentication and a bunch of other great stuff out of the box. I rarely heard technical reasons why the developers disliked WordPress itself.

I've since branched out in both front-end and back-end development, and when another developer recently asked me where WordPress is lagging behind, I thought it would be a great opportunity to write down some technical reasons I think WordPress development is painful compared to other platforms.

WordPress's pain points

WordPress lacks proper dependency management. Most WordPress sites I've worked on end up with over ten plugins, but I have no way of declaratively defining what they are or what version the site should use. As a result, a client can update or delete a plugin on accident and crash their entire site.

This is a solved problem in modern PHP and JavaScript by keeping a list of dependencies and versions in composer.json and package.json respectively

It's tedious to define custom routes in WordPress. With many back-end frameworks, adding a custom route is straight forward (Express.js example below): I would define a path, then pass it into a controller method that can parse the request and send back data.

app.get("/events/:slug", EventController.show);

With WordPress, I need to hook into the query variables and add my own, add a custom permalink structure, hook into the query to see if the custom query variable is there, conditionally edit the query, then potentially even hook into the logic that decides which template is used. I'm probably forgetting steps. All of these concerns are related, yet they are handled by separate systems in WordPress.

WordPress doesn't have a sensible native way of handling custom meta fields. The Advanced Custom Fields plugin is used by most WordPress sites to handle their custom field needs, but this is at the heart of what a content management system should do, and it's missing from WordPress.

WordPress depends on global state managed using imperative programming. Global state is harder to test and understand. Take the example below:

<?php while(have_posts()) : the_post(); ?>
  <h1><?php the_title(); ?></h1>
  <?php the_content(); ?>
<?php endwhile; ?>

If I'm not familiar with WordPress, how can I be certain that the_title() depends on the state of the loop? "Title" could refer to the title of the site instead of the post. There's no clear relationship between the_title() and the_post(). Rather than relying on the global state of the loop, these relationships could be represented as an object's properties.

<?php foreach($posts as $post): ?>
  <h1><?= $post->title; ?></h1>
  <?= $post->content; ?>
<?php endforeach; ?>

There are no surprises here: the relationship between $post and $post->title is in the code itself.

WordPress has no templating engine. WordPress templates could be more pleasant to write if they used an expressive templating engine like Blade. It would also make escaping data easier, which could help prevent certain kinds of attacks against users.

WordPress has incongruent paradigms. Despite 15 years of accumulated legacy, WordPress has gone full-speed ahead with ultra-modern React development to support its new block editor: Gutenberg. It feels out-of-step with everything else in WordPress, and Gutenberg comes with significant drawbacks. For example: if you build a block with React, you have no way to update the markup for that block across all pages other than loading and saving each page individually. Imagine doing this for a site with thousands of pages.

You can use Advanced Custom Fields to build blocks in PHP, but this is functionality that feels like it should be simple in the WordPress core.

WordPress's REST API is slow. Basic queries can take over a second to return. When I build things in Node and Laravel, I usually get response times of 200ms or less.

Are these deal breakers? Not so much.

Despite all of my problems with WordPress, it's still the best option out there for building most content-driven sites. Using platforms like React and Rails to build marketing sites requires more work than is practical in most cases, and I don't have a high degree of confidence that newer content management systems will be around in a few years' time. There's still a lot of excitement around JAMstack platforms like Hugo and Gatsby, but in my experience they have a narrow set of problems where they are actually the best tool for the job.

With WordPress powering 37% of the Internet, it has shown that architectural purity takes a backseat to end-user experience. WordPress will be democratizing the web for years to come.