Posted on by

Migrating from Underscores (_s) to Block Themes: A Developer’s Guide

If you’ve built traditional WordPress themes using Underscores (_s), you know how clean, reliable, and well-structured it is. But WordPress is evolving fast, and the new Full Site Editing (FSE) system introduces block themes that redefine how themes are built and customized.

This guide helps developers like you understand why migrating from _s to block themes is worthwhile and how to approach it step-by-step.

Why Migrate from _s to Block Themes?

The Rise of Full Site Editing (FSE)

  • Block themes enable site-wide editing through blocks — headers, footers, sidebars, and everything in between.

  • Instead of PHP templates, block themes use JSON files (theme.json) and HTML templates made up of block markup.

  • Users can customize their site visually, without touching code.

Limitations of _s in Today’s WordPress

  • _s is PHP-based and built for classic templating.

  • It doesn’t support block-based templates and patterns natively.

  • Maintaining compatibility with the latest WordPress features can become cumbersome.

Migrating lets you offer clients and users a more flexible, modern experience.

Step 1: Understand the Differences

Feature Underscores (_s) Block Themes
Template System PHP template files HTML template files with block markup
Styling Traditional CSS or Sass theme.json for global styles + CSS
Customization Theme Customizer, PHP hooks Full Site Editor, block patterns
Dynamic Content PHP functions & loops Blocks and dynamic blocks

Getting familiar with these differences will help set expectations and guide development.

Step 2: Audit Your _s Theme

  • Identify core templates and functionality in your _s theme.

  • Document custom post types, taxonomies, and any custom PHP logic.

  • Take note of your stylesheets, scripts, and assets.

Understanding what your current theme does will help you replicate or rethink those features in a block theme.

Step 3: Set Up a Block Theme Starter

There are a few options for starting a block theme:

  • Blockbase (by Automattic): A clean block theme base.

  • Create Block Theme Plugin: Helps export block themes from site editor.

  • Start from scratch: Using the WordPress Theme Handbook.

Choose one that fits your workflow.

Step 4: Convert Templates to Block Templates

  • Replace PHP template files (header.php, footer.php, etc.) with HTML files inside a /templates folder.

  • Use block markup to define your layout. For example, your header can be a group of blocks: site logo, navigation, search.

  • Use template-parts folder to organize reusable blocks, like your site footer.

Tip: Use the Site Editor in WordPress to build templates visually and export them.

Step 5: Migrate Styling to theme.json and CSS

  • Move global styles (colors, typography, spacing) to theme.json.

  • Use CSS for custom or complex styles.

  • Block themes support global styles that users can customize via the editor — so try to define flexible, theme-wide settings.

Step 6: Handle Dynamic and PHP Logic

  • Some PHP logic may need to become dynamic blocks or block variations.

  • Custom PHP in _s (like custom queries) can be converted into server-side rendered blocks or block attributes.

  • Use WordPress block APIs to register dynamic blocks as plugins or part of your theme.

Step 7: Test Extensively

  • Test across browsers and devices.

  • Ensure backwards compatibility for plugins.

  • Verify block editor experience and site editor usability.

  • Check accessibility and performance.

Step 8: Document and Train

  • Document changes and new workflows for your team or clients.

  • Train users on how to use the Site Editor and block customization.

  • Prepare for ongoing maintenance as FSE evolves.

Final Thoughts

Migrating from Underscores to block themes is more than just a rewrite—it’s embracing a new way of thinking about WordPress theming. It may feel unfamiliar at first, but it unlocks a powerful, flexible design system that puts more control in the hands of users and developers alike.

If you want your themes to stay relevant and leverage WordPress’s latest features, block themes are the future. With this guide, you have a roadmap to start your migration journey confidently.

If you want, I can also help with sample code snippets for block templates or dynamic blocks to kickstart your migration!