22 de April de 2025 Web development

Developing WordPress projects with Gutenberg blocks and modular architecture

Our recipe for scalable, maintainable, and business-oriented code

TL;DR: We start from a clean WordPress installation, add ACF Pro, define an almost empty template, and build our own MVC core. Each Gutenberg block lives in its own folder, with fields and styles bundled via Webpack. The result: a site that grows in an organized way, deploys with a simple git push, and empowers the marketing team to build pages without relying on developers.

1. Starting point: no bloat, maximum freedom

One of the most common mistakes in custom WordPress projects is starting with a theme that’s too complex, overloaded with styles, plugins, and configurations that are hard to manage later. Our approach is exactly the opposite.

We start with a clean WordPress installation.
We install Advanced Custom Fields (ACF) Pro, allowing us to create custom blocks via code, without relying on the backend or database.
We build our own theme with only what’s essential: style.css with theme metadata and a functions.php that only loads our modular system.

This minimal setup gives us full control over the behavior and evolution of the project.

2. “Functions” and “Style”: less is more

Two of the most problematic files in WordPress development are functions.php and style.css. It’s common to find projects where these files hold hundreds or thousands of lines of code, making them hard to maintain and prone to errors.

Our approach focuses on specialization and simplicity:

functions.php

Contains: a single line that loads core/autoload.php
Does not contain: hooks, business logic, queries, etc.

style.css

Contains: theme metadata
Does not contain: global styles

We want each file to serve a single purpose. If logic or styles are needed, they go in the file specific to the block or functionality.

3. A custom MVC core: structure, clarity, and growth

At the heart of the system is our core/ folder, organizing the project in a structure similar to the Model-View-Controller (MVC) pattern. We don’t follow it dogmatically, but adapt it to WordPress’ nature.

General structure:

core/
 ├─ controllers/     ← Handle requests (AJAX, hooks...)
 ├─ services/        ← Execute business logic
 ├─ repositories/    ← Access to databases or external APIs
 ├─ helpers/         ← Reusable helper functions
 └─ configuration/   ← WP setup, scripts, post types, options...

Real example:

A form AJAX request hits a controller.
The controller calls a service to validate data and make decisions.
The service invokes a repository to save data to the database and send it to a CRM.

This approach enables pain-free scalability. Each new use case becomes a new service and, if needed, a new repository. Nothing more.

Build WordPress projects with Gutenberg blocks and modular architecture

4. 100% custom Gutenberg blocks: design and control

One of the keys to success in these projects is the creation of custom Gutenberg blocks. Each block is a fully modular component, custom-built with a fixed structure that facilitates teamwork:

blocks/
 └─ featured-product/
     ├─ block.json         ← Block metadata
     ├─ fields.json        ← Block fields (via ACF JSON)
     ├─ block.php          ← Render logic
     ├─ block.scss         ← Local styles
     └─ template-parts/   ← Reusable template fragments

Benefits for the end client:

Total flexibility without technical knowledge: the content team can build full landing pages by dragging blocks.
Visual consistency: all blocks follow the brand’s style guidelines.
Publishing speed: no need to contact devs to launch a new campaign.

5. Communication between blocks: events, not dependencies

A particularly elegant technical point was managing block interactions using JavaScript events. This upholds the principle of component independence.

Example:

The “form” block dispatches a lead:stored event when a user registers.
The “thank you message” or “loading spinners” blocks listen to the event and respond accordingly.

This allows any part of the UI to react without coupling or cross-calls between blocks. A much cleaner and more predictable architecture.

6. Built for marketing teams

This structure not only helps developers, but also empowers marketing teams managing site content. It’s designed to ease their work, reduce errors, and speed up publishing:

Error-free visual editing: blocks are designed so content doesn’t break the layout.
Custom options: each block exposes only the necessary settings (colors, images, number of columns…).
Internal documentation: each block includes comments and examples for use.
100% custom blocks: no generic WordPress blocks. Each one is developed for the client’s specific needs.
Setup in seconds: adding, configuring, and publishing a block takes under 30 seconds.
Pre-designed layout: content has a defined design. Editors just fill in the text and choose options—no worries about the final look.
Multiple preconfigured styles: each block can have different visual variants selectable with one click.
Drag-and-drop dynamic forms: building a full form is as easy as selecting the fields you need—the system handles the rest.
Automatic CRM integration: every lead from forms goes directly to the client’s CRM—no manual steps.

In short, this system allows content to grow without relying on the tech team, while ensuring visual consistency and operational efficiency.

7. Continuous deployment and multi-environment

For many of our clients, a key concern is that development improvements reach production safely, quickly, and without errors.

All configuration is stored in JSON files.
Development, staging, and production environments share the same code.
Deployment is just a git pull and a cache clear. That’s it.

In some projects we’ve worked with multiple domains sharing the same code and changing only visual appearance via profiling folders. It’s a highly reusable and long-term efficient system.

8. Webpack bundling: performance from second one

Each Gutenberg block includes its own SCSS and JS files. Instead of loading dozens of scripts separately, we use Webpack to:

Minify and bundle files per block.
Optimize load times and overall performance.
Avoid conflicts and ensure each component is isolated.

This leads to better Core Web Vitals metrics and a smooth user experience from the very first second.

9. Conclusion: professional development, visible results

Our approach blends the best of both worlds:

The technical advantages of a modular, scalable, and well-thought-out architecture.
The business impact of a system that lets you create pages, launch campaigns, and update content in minutes.

Whether you’re a marketing manager, CTO, or project lead, this kind of structure ensures:

Fewer errors.
Faster development.
More control over project evolution.

Let’s talk?

If you’re interested in this approach and looking for a company that doesn’t just code WordPress but thinks long-term about your site, get in touch with us.

We develop technically solid projects, with a clear and maintainable codebase, and the flexibility your content team needs to grow.