Migrating from a classic WordPress theme to a block theme is one of the most impactful technical decisions you can make for a WordPress site in 2026. The benefits are real, faster load times, a native Site Editor experience, better Core Web Vitals, and a codebase that aligns with where WordPress is heading. But the migration also carries real risks: broken layouts, lost customizations, confused content editors, and a poor launch experience if you rush it. This guide gives you a complete, ordered process for migrating safely, with a focus on protecting your live site at every step.
Treat migration as a project, not a task. Do not expect to swap themes and call it done. Plan for a two-to-four week process depending on site complexity, with parallel environments, structured QA, and a defined rollback path. Following that discipline is what separates migrations that go smoothly from ones that generate panicked client calls at midnight.
Understanding What You Are Actually Migrating
Before you write a single line of theme code, you need to audit what your classic theme actually does. Most developers underestimate the scope of a migration because they focus on the visual design and forget the functional layers underneath. A complete audit should cover four categories.
The first category is templates. Classic themes use PHP template files, index.php, single.php, archive.php, page.php, and dozens of potential variations, that contain business logic, conditional content, and markup structure mixed together. Each of these needs a block theme equivalent, either as a block template HTML file or as a combination of template parts and patterns.
The second category is functions.php logic. Classic themes often accumulate significant functionality in functions.php over time: custom post type registrations, shortcode definitions, ACF field group registrations, custom widget areas, nav menu registrations, and hook-based customizations. Some of this logic belongs in a plugin and should be extracted before migration. The rest needs to be evaluated for block theme equivalents or preserved carefully.
The third category is styling. Classic themes have CSS that targets markup structures which will no longer exist in the block theme. The class names, nesting patterns, and HTML structure are fundamentally different between classic theme markup and block markup. You cannot port CSS directly, you need to rebuild styles in theme.json and per-block style overrides.
The fourth category is widget areas and sidebars. Classic themes frequently use widget areas for sidebars, footers, and other content zones. Block themes do not have traditional widget areas, that functionality is replaced by block template parts, patterns, and the block-based widget editor. Your widget content needs to be manually migrated into block patterns or template parts.
Understanding these four categories before you start gives you a realistic picture of migration scope. A simple brochure site might take two to three days. A complex site with custom templates, heavy functions.php logic, and multiple widget areas could take two to three weeks.
Step 1: Set Up Your Staging Environment
Never begin a migration on your live site. Start by creating a complete staging environment, a full copy of your WordPress installation including the database, files, and uploads directory. Most managed WordPress hosts (WP Engine, Kinsta, SiteGround, Cloudways) have one-click staging environments. If your host does not, use a plugin like WP Staging to create a copy, or clone the site to a local development environment using Local by Flywheel or DevKinsta.
Your staging environment should be a true copy of production, not a minimal test install. This is critical because migration problems often appear in real content, long posts with unusual formatting, media-heavy pages, custom field data, that you would not encounter with placeholder content. Test with real data and you will catch real problems.
Once staging is ready, configure it to be blocked from search engine indexing (most hosts do this automatically for staging environments, but verify). Also disable any third-party integrations that should not fire against real external services, email sending, payment processing, CRM webhooks, and analytics tracking should all be disabled or pointed at test endpoints in staging.
With staging ready, install your block theme alongside the existing classic theme without activating it yet. This lets you explore the block theme structure in the Site Editor without affecting any of your site’s current content or styling.
Step 2: Extract Theme Logic Into a Plugin
This step is one that experienced developers know to do and everyone else skips, and then regrets. Before you migrate your theme, audit your classic theme’s functions.php and extract any logic that is not strictly presentational into a site-specific plugin.
Logic that belongs in a plugin rather than a theme:
- Custom post type and custom taxonomy registrations
- Shortcode definitions
- Custom REST API endpoints or modifications
- ACF field group registrations and ACF pro settings
- WooCommerce customization hooks (product display, pricing, cart modifications)
- Custom user roles and capabilities
- Admin customizations, custom columns, admin menus, dashboard widgets
- Email template overrides
- Any business logic that would be painful to lose if you switch themes again in the future
The rule of thumb is: if deactivating your theme should not break this feature, it belongs in a plugin. Create a mu-plugin or a simple site-specific plugin, move this code there, verify it still works, and then proceed with the theme migration. This step makes your site more maintainable regardless of whether you are migrating themes.
Step 3: Build Your theme.json Foundation
Theme.json is the control center of a block theme. It defines your color palette, typography scale, spacing scale, layout widths, and per-block style defaults. Before you build any templates, you need a solid theme.json that captures your site’s design system. This is the translation layer between your classic theme’s CSS variables and design tokens and the block theme’s styling system.
Start by documenting your classic theme’s design tokens from its CSS or SCSS source files:
- Primary, secondary, accent, and background colors
- Font families used (body text, headings, monospace)
- Font size scale (small, base, medium, large, XL, 2XL)
- Spacing scale (the increments used for margins, padding, gaps)
- Maximum content width and wide/full-width breakpoints
- Border radius values used for cards, buttons, images
- Box shadow values
Map each of these into theme.json settings. Your colors go into settings.color.palette. Font families go into settings.typography.fontFamilies with fontFace declarations for self-hosted fonts. Font sizes go into settings.typography.fontSizes, and if you want fluid type that scales with viewport width, enable settings.typography.fluid and set fluidFontSize on each size preset. Spacing scale goes into settings.spacing.spacingSizes. Layout widths go into settings.layout.contentSize and settings.layout.wideSize.
Getting this right before building templates saves enormous time. Every template you build will inherit from theme.json, so if your design tokens are correct there, your templates will look right by default rather than requiring per-block style overrides everywhere.
Step 4: Recreate Templates in the Block Theme
With theme.json in place, start building your block templates. The WordPress template hierarchy in block themes mirrors the classic theme hierarchy closely, so you can map your classic theme’s PHP templates to block theme HTML templates on a one-to-one basis in most cases.
The recommended order for building templates is:
- Template parts first: Build your header and footer template parts before any page templates. Every other template will include these, so getting them right first saves rework. Use the Site Editor’s template part editor or build the HTML files directly in your theme’s
parts/directory. - index.html: The fallback template. Keep it simple, header, main content area with a Query Loop block for archive contexts or a single post block for single contexts, footer.
- single.html: Your single post template. This typically includes the post title, featured image, post content, author info, and comment block.
- page.html: Your default page template. Usually simpler than single.html, title, content, no author or comment block unless needed.
- archive.html: Your archive template using the Query Loop block configured for archive context.
- Category, tag, and taxonomy templates: Variations of archive.html with category/taxonomy-specific headers.
- Custom templates: Any page-specific templates your classic theme had, full-width, no-sidebar, landing page variants.
The Site Editor is valuable during this process because it lets you visually preview templates against real content while you build. Use it alongside direct file editing for the best workflow, edit the HTML file, reload the Site Editor to see the result, adjust, repeat.
Step 5: Migrate Widget Content to Patterns and Template Parts
Widget areas are one of the trickiest parts of classic-to-block migrations because there is no automated conversion. Each widget area and its contents need to be manually rebuilt in the block editor.
The mapping is straightforward once you know it:
- Header widget areas → Block template part (header.html) with blocks for search, navigation, and custom content
- Sidebar widget areas → Block pattern or a dedicated sidebar template part included in single.html and page.html templates
- Footer widget areas → Block template part (footer.html) built with columns and blocks
- Text widgets → Paragraph and Heading blocks
- Image widgets → Image block
- Recent Posts widgets → Query Loop block configured for recent posts
- Custom HTML widgets → Custom HTML block
- Navigation menu widgets → Navigation block
For complex sidebar content, advertising blocks, newsletter signup forms, related content lists, evaluate whether a block or a block pattern can replace the widget behavior directly. Most common widget use cases have direct block equivalents in 2026.
Step 6: Handle Classic Post Content in the Block Editor
This is the area that surprises most developers during migration. Your existing post content was written in either the classic TinyMCE editor or an early version of the block editor. When you switch to a block theme, this content does not automatically reformat itself to match your new theme’s styling.
Content that uses classic editor markup, HTML tables, legacy shortcodes, manually applied inline styles, embedded iframes, will render in the block editor’s Classic block, which applies a sanitized version of the classic editor’s default styles. These Classic blocks will look different from content written natively in the block editor.
Your options for handling this content:
- Leave it as Classic blocks for lower-priority pages. The content still renders correctly, just without block editor styling benefits. This is acceptable for archived or low-traffic content.
- Manually convert high-priority pages using the block editor’s “Convert to Blocks” feature on the Classic block. This works well for straightforward content but may require cleanup of inline styles and legacy formatting.
- Use the Block Transform API for bulk conversions if you have a large volume of similar content. This requires developer work but can automate conversion at scale.
- Shortcode content needs special attention, if your classic theme registered shortcodes via functions.php, those shortcodes need to either remain registered (via your site-specific plugin from Step 2) or be replaced with equivalent blocks.
Do not try to migrate all existing post content at once. Prioritize your highest-traffic pages and most recent posts. Older archive content can be addressed gradually over weeks or months after launch.
Step 7: QA Checklist Before Going Live
Before activating the block theme on your live site, run through a complete QA checklist on staging. This checklist covers the most common migration failure points.
- Homepage renders correctly at all breakpoints (desktop, tablet, mobile)
- Blog archive page shows correct number of posts per page with correct pagination
- Single post template renders correctly including featured image, author, date, categories, and comments
- All navigation menus appear in the correct locations and function correctly
- Search functionality works, form submits, results page renders with correct template
- 404 page renders with the block theme’s 404.html template
- All forms on the site submit correctly (contact forms, newsletter signup, WooCommerce checkout)
- WooCommerce pages (shop, product, cart, checkout, account) render correctly
- Custom post types and taxonomies have correct template coverage
- All shortcodes render correctly (they should, if Step 2 was done correctly)
- Site loads correctly when not logged in (admin bar presence changes layout slightly)
- Core Web Vitals measured in staging, verify LCP, CLS, and FID/INP improvements
- Google Search Console integration still works (site verification meta tag)
- Analytics tracking fires correctly (GA4 or equivalent)
- Social sharing meta tags render correctly (Open Graph, Twitter Card)
- RSS feed is valid and renders correctly
- Sitemap is valid and reflects current content
Run through this checklist manually and document any issues. Fix issues on staging before cutover. For the developer migration guide with deeper technical context, the complete developer’s migration guide covers advanced scenarios including child theme handling and multisite considerations.
Step 8: The Cutover Process
When staging QA passes, you are ready for cutover. Plan this carefully, do not do it on a Friday afternoon before a weekend, and do not do it during your site’s highest-traffic period. Schedule the cutover for a low-traffic window and allocate monitoring time immediately after.
Cutover steps in order:
- Take a complete database backup of production immediately before cutover
- Take a complete files backup of production (especially wp-content)
- Upload the block theme files to production
- Activate the block theme in Appearance > Themes
- Verify homepage immediately, do not leave the admin area before confirming the front page renders
- Check navigation menus, they may need to be reassigned to new block theme menu locations
- Verify the Site Editor is accessible and templates are correct
- Check five to ten key pages manually at different content types
- Verify forms submit and email sends
- Check Google Analytics is firing (use Real-Time view)
- Monitor server error logs for the next 30 minutes
Keep your classic theme installed (but not active) for two to four weeks after launch. This gives you an instant rollback path if you discover a problem that requires more time to fix than you can address with the block theme active.
Handling Third-Party Plugins During Migration
Third-party plugins are often the source of the most unexpected migration problems. Most plugins that render front-end output do so by hooking into WordPress actions and filters, which are theme-agnostic and will continue to work after theme migration. However, some plugins have styling that is tightly coupled to classic theme markup, they target theme-specific CSS class names, assume sidebar layouts, or inject styles that conflict with theme.json’s global styles.
Page builder plugins that create content, Beaver Builder, Divi, WPBakery, are the most problematic. Content created with these builders is stored as shortcodes or custom markup in the post content. In a block theme, this content will render through the Classic block or as raw shortcode output. If you are on a site that used a page builder extensively, each page builder-created page needs to be rebuilt in the block editor. There is no shortcut here.
For contact form plugins (Contact Form 7, WPForms, Gravity Forms), the forms themselves migrate fine, they are registered by the plugin and rendered via shortcode or block, not by the theme. What may need attention is the styling of form fields, error messages, and success states, since these inherit from your theme’s stylesheet. With a block theme, form styles are controlled through theme.json color, typography, and spacing settings plus any custom CSS you add to the theme or the plugin’s custom CSS field.
For WooCommerce specifically: if you are migrating a WooCommerce site, run the WooCommerce system status check before and after migration. Verify that all WooCommerce template overrides in your classic theme have equivalents in the block theme, either through WooCommerce’s block templates or through custom template overrides in your block theme’s templates/woocommerce/ directory. WooCommerce compatibility with block themes has improved dramatically, but custom template overrides from classic themes need to be explicitly rebuilt for the block theme context.
FAQ: Classic to Block Theme Migration
Q: Will my Yoast or RankMath SEO settings transfer when I switch themes?
A: Yes. SEO plugin settings (meta titles, descriptions, Open Graph data, schema markup) are stored in the WordPress database against posts and site-wide settings, not in your theme. Switching themes does not affect your SEO plugin data. Your redirects, canonical URLs, and sitemap configurations all remain intact. The only SEO risk in migration is if your new block theme changes URL structures (which it should not) or renders content in a way that affects crawlability (verify with Screaming Frog or Sitebulb after launch).
Q: Do I need to rebuild my child theme when migrating to a block theme?
A: Classic child themes do not translate to block theme child themes. Block theme child themes work differently, they override templates and styles from the parent theme using the same HTML/JSON file structure, not PHP template overrides. If you have a classic child theme, audit what customizations it makes and rebuild those as block theme template overrides, style variations in theme.json, or additional block patterns. The child theme concept still exists for block themes, but the implementation is entirely different.
Q: What happens to my Customizer settings after switching to a block theme?
A: The classic WordPress Customizer is largely replaced by the Site Editor in block themes. Settings you configured in the Customizer, site title, logo, background color, header settings, menu locations, need to be reconfigured in the Site Editor. The Customizer data is stored in the database as theme mods, which are theme-specific, so they do not carry over when you switch themes. Document all your Customizer settings before migration and recreate them in the Site Editor after activation. This typically takes 15–30 minutes for a standard site.
After Migration: Ongoing Block Theme Maintenance
Once your block theme is live, the maintenance story is genuinely simpler than classic themes. There are no PHP template files that need PHP version compatibility checks. There are no widget registrations to maintain. Theme.json changes propagate globally without CSS specificity battles. When WordPress updates, block theme compatibility is generally seamless because the block markup standard is maintained by core.
The main ongoing tasks for a block theme site are pattern library maintenance (adding new patterns as your design needs evolve), theme.json updates when WordPress introduces new settings support, and keeping your site-specific plugin updated if you extracted logic there in Step 2. For teams, establishing a process for making template changes through version control, rather than through the Site Editor alone, is important for sites where multiple developers work on the same codebase.
The guide to building a WordPress block theme from scratch is a useful resource for understanding the file structure and conventions that will serve you well in ongoing maintenance, even if you migrated rather than built from scratch.
Block theme migration is a significant project but a worthwhile one. The sites that come out the other side are faster, more maintainable, better aligned with WordPress’s development direction, and free from the commercial plugin dependency that page builder-based sites carry. The process is predictable if you follow the steps in order, test thoroughly on staging, and resist the temptation to rush the cutover.