Recently, I had the opportunity to take the stage to discuss a topic I live and breathe every day at CNN Brasil: Headless WordPress.

The idea behind the talk wasn’t just to show code, but to be open about what actually happens when one of the country’s largest news portals decides to separate its back-end from its front-end. For those who couldn’t make it (or for those who were there and want a refresher), I decided to highlight the key points of that conversation here.

The “Dark Kitchen” Analogy

I started the presentation by trying to demystify the technical concept. Many people think Headless is overly complicated, but I like comparing it to restaurants.

Traditional WordPress is like a classic restaurant: it has an integrated dining room and kitchen. It’s practical and works well, but the structure of the dining room limits how you serve the dish.

Headless, on the other hand, is a “Dark Kitchen”. There is no dining room. The focus is on producing the dish (content) with maximum quality in the kitchen (wp-admin) and delivering it wherever the customer is: whether via delivery, takeout, or an app. In practice, this means WordPress focuses on the data, while Next.js (in our case) focuses on the user experience.

The Elephant in the Room 🐘

I didn’t want to sell illusions. I made a point of highlighting that migrating to Headless brings challenges that are often ignored amidst the technology hype. I highlighted four main pain points we faced:

1. Reinventing the wheel: Basic Core WP features, like draft previews and rewrite rules, need to be recreated from scratch on the front-end.
2. Incompatible plugins: Forget about most visual plugins or page builders. If it doesn’t have an API, it won’t work.
3. Cache Control: Orchestrating the cache between what the editor saves and what the user sees is much more complex.
4. Documentation: There are plenty of basic tutorials online, but very little advanced content regarding real-world architecture problems.

But… Is it worth it? (Spoiler: Yes, for the right use case)

Despite the pain points, I showed why this choice transformed CNN Brasil. It wasn’t j“modernization”; it was a real business gain.

I discussed “Freedoms” we achieved:

• Performance: Our site flies. Separating responsibilities lifted the weight off WordPress.
• Security: If no one knows where your /wp-admin is, no one attacks your login.
• Talent: Today, we attract developers who want to work with React, Next.js, and modern architectures.

And the numbers I presented don’t lie. After a year of development and over 40,000 lines of code, we saw a huge audience growth, hitting peaks of 250 million pageviews. Today, we are the largest WordPress portal in Brazil.

The Decision Checklist

To close the talk, I left a “roadmap” for anyone thinking about following this path. Headless isn’t for everyone (and that’s okay!).

If you are considering it, ask yourself the questions I showed on the final slide:

• Do you need to distribute content to Apps and other channels?
• Is your team ready to maintain a software application and not just a site?
• Do your essential plugins have APIs?
• Does the site pay for itself? (This is crucial: complexity has a cost).

If the answer is yes, Headless is a one-way street to freedom and performance.

I would like to thank everyone who watched and sent questions. It was amazing to exchange experiences about software architecture with the community.