Classic vs block themes: real-world lessons and examples

By day 28, you've built enough WordPress functionality to face a critical architectural decision: should your next theme project embrace block-based development, stick with the classic PHP template approach, or chart a hybrid course? The question of classic vs block themes: real-world lessons and examples matters because the choice shapes your entire workflow, client maintenance burden, and long-term scalability.

Understanding block themes and theme.json

Block themes represent WordPress's shift toward a configuration-driven model. Instead of PHP templates controlling layout, you define design systems in theme.json, and the full-site editor (FSE) lets clients modify pages, headers, and footers without touching code.

Here's a minimal block theme structure:

/my-block-theme
├── theme.json
├── functions.php
├── templates/
│   ├── index.html
│   ├── single.html
│   └── archive.html
├── parts/
│   ├── header.html
│   ├── footer.html
│   └── sidebar.html
└── patterns/
    └── hero.php

In theme.json, you define color palettes, typography scales, and spacing systems that cascade across all templates:

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "name": "Primary", "slug": "primary", "color": "#0073aa" },
        { "name": "Secondary", "slug": "secondary", "color": "#005a87" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "name": "Small", "slug": "small", "size": "0.875rem" },
        { "name": "Large", "slug": "large", "size": "2.25rem" }
      ]
    }
  },
  "styles": {
    "color": {
      "background": "var:preset|color|white"
    }
  }
}

A real-world benefit emerged when we built a SaaS onboarding platform theme. The marketing team needed to test color variations without developer intervention. With block themes, they adjusted the palette in theme.json and saw changes live across 40+ templates instantly. In a classic theme, that same task required PHP overrides and testing across multiple template files.

Block themes shine for content-heavy sites where non-technical users manage layout frequently. The FSE provides a visual interface that reduces support tickets significantly.

Classic themes: PHP templates and developer control

Classic themes use PHP to render templates, giving you fine-grained control over output, performance optimization, and complex conditional logic. You write template files like single.php, archive.php, and functions.php to shape every aspect of rendering.

<?php
// single.php in a classic theme
get_header();

while ( have_posts() ) {
    the_post();
    
    // Custom logic for post type handling
    if ( 'case_study' === get_post_type() ) {
        echo '<div class="case-study-hero">';
        echo get_the_post_thumbnail( null, 'hero-size' );
        echo '</div>';
    }
    
    // Conditional sidebar rendering
    if ( ! is_singular( 'page' ) ) {
        get_sidebar();
    }
}

get_footer();

We chose classic architecture for a travel booking platform where performance was non-negotiable. The theme needed to conditionally load scripts based on post type, cache expensive queries, and strip unnecessary markup for mobile users. PHP templates let us inject caching headers, defer non-critical CSS, and conditionally render entire sections based on custom post meta.

Classic themes work well when:

• You need strict performance budgets or complex caching strategies
• Clients have minimal content management needs
• The design system includes intricate component interactions
• You integrate deeply with third-party APIs and custom post types

The downside: maintaining classic themes requires more developer effort, and non-technical users can't modify templates visually.

Hybrid approaches: the pragmatic middle ground

Many production environments don't fit neatly into block-only or PHP-only camps. Hybrid themes combine block theme flexibility with classic theme power, using theme.json for design tokens while keeping custom PHP templates for complex pages.

A hybrid might look like this:

/hybrid-theme
├── theme.json (design system)
├── functions.php (setup and hooks)
├── templates/
│   ├── index.html (block template)
│   ├── single.html (block template)
│   └── single-product.php (classic PHP for complex product logic)
├── parts/
│   ├── header.html
│   └── footer.html
└── inc/
    ├── custom-post-types.php
    └── template-functions.php

In functions.php, you register block patterns and enqueue custom scripts selectively:

add_action( 'init', function() {
    // Register custom block pattern for product showcase
    register_block_pattern(
        'my-theme/product-grid',
        array(
            'title'       => 'Product Grid',
            'description' => 'Three-column grid of featured products',
            'content'     => '...',
        )
    );
    
    // Load critical CSS for all pages
    wp_enqueue_style( 'theme-critical', get_template_directory_uri() . '/css/critical.css' );
} );

We built a B2B SaaS dashboard using this hybrid approach. Public-facing pages used block templates, letting the marketing team iterate on landing pages. The dashboard itself—a complex, role-based interface—remained a classic PHP template with custom queries and permission checks. This split reduced cognitive load: marketers owned their space, engineers owned theirs.

New projects favor block themes—here's why

WordPress core development momentum has shifted decisively toward block themes. WordPress 6.0+ includes improved FSE stability, better block patterns library, and expanding plugin support for theme.json customization. New client projects increasingly request "modern" interfaces, and block themes deliver that expectation.

Performance concerns that once favored classic themes have mostly been addressed. Modern block themes generate lean HTML, and you can still optimize aggressively:

// Block theme functions.php with performance optimizations
add_filter( 'block_loader_should_load_separate_core_block_assets', '__return_true' );

add_action( 'wp_enqueue_scripts', function() {
    // Defer non-critical fonts
    wp_enqueue_style( 'theme-fonts', '...', array(), null );
    wp_style_add_data( 'theme-fonts', 'async', true );
    
    // Preload critical resources
    echo '<link rel="preload" as="image" href="' . esc_url( get_template_directory_uri() . '/images/hero.webp' ) . '">';
} );

For e-commerce and SaaS platforms launching today, block themes reduce onboarding friction. Clients expect visual builders; delivering one speeds handoff and reduces support overhead. Template management is simpler (HTML instead of PHP), and design updates propagate instantly across the site.

We started three projects in 2024 with block themes, and only one required dropping back to custom PHP for a specialized checkout flow. The other two thrived entirely on blocks, patterns, and theme.json—something impossible to achieve five years ago.

Common mistakes

Mistake 1: Choosing blocks when you need PHP. Not every site is block-suitable. A reservation system with complex validation logic, a trading platform with real-time data streams, or a membership site with elaborate access control benefit from classic template control. Don't force blocks where classic architecture is clearer.

Mistake 2: Treating theme.json as optional in block themes. Developers familiar with classic themes often skip theme.json and jump to custom CSS. This defeats the purpose of block themes. Invest in theme.json from day one; it's your design system contract with the client.

Mistake 3: Overcomplicating hybrid themes. Hybrid approaches work, but they double maintenance surface area. Use them only when you have a concrete reason to split PHP and blocks. Don't split just to hedge your bets.

Mistake 4: Ignoring plugin support for blocks and theme.json. Many plugins haven't adapted to block themes. Before committing to blocks, audit your required plugins. A critical form builder or booking system that only works with classic shortcodes derails a block theme project.

Key takeaways

• Block themes use theme.json for design systems and HTML templates, enabling full-site editing and non-technical content management. Choose them for new projects when clients need visual flexibility.
• Classic themes use PHP templates for granular control over rendering, caching, and conditional logic. They're still the right choice for complex applications and performance-critical sites.
• Hybrid themes combine both approaches—blocks for public content, PHP for specialized templates. Use them only when you have a genuine split in architecture needs.
• Block theme tooling and performance have matured significantly. 2024's WordPress ecosystem strongly favors blocks for new projects; the catch-up game isn't worth playing for most teams.
• Plugin compatibility is your largest wildcard. Audit before committing; a block-incompatible dependency can sabotage your entire theme strategy.