Introduction

Full Site Editing (FSE) represents a paradigm shift in how WordPress sites are designed and managed. Rather than separating theme development from content editing, FSE enables site builders to edit every aspect of their site—from header to footer, template to template—directly in the Block Editor. However, this architectural transformation creates new challenges for WordPress full site editing plugin compatibility.

Plugins built for classic WordPress themes may not work as expected in FSE environments. Features that relied on PHP-based template hierarchies or custom theme modifications need to be rethought for block-based architectures. Understanding FSE architecture and planning for compatibility from the start is essential for building modern WordPress plugins that work seamlessly with both classic and block-based themes.

This guide explores FSE fundamentals, the theme.json configuration system, the differences between block themes and classic themes, and practical strategies for ensuring your plugins work correctly in FSE environments. WP HealthKit helps identify compatibility issues in your plugins by analyzing their interactions with FSE architecture.

Understanding FSE Architecture

Full Site Editing fundamentally changes how WordPress renders pages and manages site appearance. In classic WordPress, themes are PHP-based, with template files like header.php, sidebar.php, and footer.php controlling the site structure. Custom post types, meta boxes, and plugin output are integrated through hooks and filters scattered throughout these templates.

FSE inverts this architecture. Instead of PHP templates, FSE uses block-based templates stored as post content. A site's header, footer, and page layouts are all composed of blocks, the same blocks that content editors use to create posts. This creates a more unified editing experience but requires plugins to adapt.

This fundamental shift has profound implications for how plugins interact with WordPress. In the classic theme model, a plugin might hook into the wp_footer action to inject custom HTML or CSS, relying on the theme to call that action at the right place. In FSE, that hook-based approach becomes obsolete because there are no PHP templates to hook into. Instead, plugins must participate in the block-based system by registering blocks that site editors can place and configure directly.

Understanding this transition is critical for plugin developers looking to maintain compatibility with modern WordPress. The change isn't just technical—it's a philosophical shift from plugins extending through code hooks to plugins providing reusable, configurable components that editors can use directly. This shift improves the editing experience and security because site builders have more visibility into what plugins are doing on their sites.

The FSE architecture consists of several key components:

Block Themes are built entirely from blocks and templates. They have no classic PHP template files. A block theme defines its structure, styling, and functionality through template/ directories containing template parts stored as HTML blocks.

Theme.json is a configuration file that defines site-wide settings like colors, typography, spacing, and available blocks. It's the primary mechanism for controlling how blocks behave and appear across the site.

Template Parts are reusable block compositions that appear in multiple templates. Your header, footer, navigation, and sidebar might all be template parts that you can edit in one place.

Global Styles allow site builders to define consistent styling across the entire site through the Site Editor interface, eliminating the need for custom CSS in many cases.

Understanding this architecture helps you design plugins that work with FSE rather than against it.

Theme.json Integration Guide

The theme.json file is the control center for FSE sites. It defines what settings and styles are available to site builders, which blocks are enabled, and how blocks behave. For plugin compatibility, understanding theme.json is essential.

The theme.json specification represents a declarative approach to theme configuration that replaces scattered CSS custom properties, PHP theme support declarations, and JavaScript enqueue operations. Instead of plugins and themes fighting over styling decisions through CSS specificity battles, theme.json provides a centralized source of truth for the entire site's design system. This configuration-driven approach brings consistency and predictability to FSE-based sites.

When designing plugins for FSE compatibility, working with theme.json is not optional—it's a requirement if you want your plugin to integrate smoothly into modern sites. Plugins that respect theme.json values inherit the site's design system automatically. Plugins that hardcode colors, spacing, and typography values create disconnects and maintenance headaches for site builders who can't apply their design system consistently.

The beauty of theme.json is that it enables powerful site-wide design changes. When a site builder updates the color palette in theme.json, every block on the site that uses those colors updates automatically. Plugins that respect this system provide a seamless experience where their blocks and content adapt to design changes without requiring manual updates.

A basic theme.json structure looks like:

{
  "$schema": "https://schemas.wp.org/wp/6.3/theme.json",
  "version": 2,
  "settings": {
    "appearance": {
      "enableCustomLineHeight": true,
      "enableCustomSpacing": true
    },
    "typography": {
      "fontSizes": [
        {
          "name": "Small",
          "slug": "small",
          "size": "0.875rem"
        }
      ]
    },
    "color": {
      "palette": [
        {
          "color": "#ffffff",
          "name": "White",
          "slug": "white"
        }
      ]
    }
  },
  "styles": {
    "typography": {
      "fontSize": "1rem"
    }
  }
}

Plugins can extend theme.json to register custom settings and styles. If your plugin provides custom blocks, you might extend theme.json to provide default styling:

function my_plugin_register_block_styles() {
  $theme_json = array(
    'version'  => 2,
    'settings' => array(
      'blocks' => array(
        'my-plugin/testimonial' => array(
          'color' => array(
            'palette' => array(
              array(
                'color' => '#f0f0f0',
                'name'  => 'Light Gray',
                'slug'  => 'light-gray',
              ),
            ),
          ),
        ),
      ),
    ),
  );

  wp_register_script_module(
    '@my-plugin/block-styles',
    plugin_dir_url( __FILE__ ) . 'block-styles.js',
    array( 'wp-blocks', 'wp-dom-ready' ),
    filemtime( plugin_dir_path( __FILE__ ) . 'block-styles.js' )
  );

  wp_enqueue_script_module( '@my-plugin/block-styles' );
}

add_action( 'init', 'my_plugin_register_block_styles' );

For FSE compatibility, your plugin should not force custom styling if theme.json provides a way to achieve the same result. Allow site builders to customize your plugin's appearance through theme.json rather than hardcoding styles.

Block Themes vs Classic Themes

Block themes are built entirely from blocks, while classic themes still use PHP templates. Understanding the differences helps you design plugins that work with both.

The divide between block themes and classic themes represents a generational shift in WordPress theme development. Block themes, introduced fully in WordPress 5.9, mark the end of the era where themes were exclusively PHP templates. While classic themes will remain supported for years to come, block themes represent the future of WordPress theme development and should be your primary target when designing new plugins.

Classic themes use template hierarchy with PHP files like single.php, archive.php, and page.php. Plugins hook into these templates with functions like wp_footer(), wp_head(), and sidebar output. Custom styling typically requires adding CSS through wp_enqueue_style(), and custom functionality is added through hooks scattered throughout theme code. This approach has served WordPress well for two decades, but it creates tight coupling between plugins and themes. A plugin might assume the theme has a sidebar, or that certain hooks exist, or that specific CSS selectors are available.

Block themes eliminate this coupling by providing a consistent, predictable structure. There are no PHP template files to hook into because there are no PHP template files. Instead, everything is blocks and configuration. This shift initially seems disruptive, but it actually simplifies plugin development by removing assumptions about theme structure.

// Classic theme approach - relies on theme hooks
function my_plugin_add_widget() {
  echo '<div class="my-widget">';
  echo apply_filters( 'my_plugin_widget_content', 'Default content' );
  echo '</div>';
}

add_action( 'wp_footer', 'my_plugin_add_widget' );

Block themes have no PHP template files. Instead, templates are stored in the database or files as block markup. The entire site is edited as blocks, including the header and footer. Plugins for block themes must register custom blocks or modify block behavior.

// Block theme approach - provides custom blocks
function my_plugin_register_block() {
  register_block_type(
    'my-plugin/widget',
    array(
      'editor_script'   => 'my-plugin-editor',
      'render_callback' => 'my_plugin_render_widget',
    )
  );
}

add_action( 'init', 'my_plugin_register_block' );

A plugin that works with both architectures must detect which type of theme is active and adjust accordingly:

function my_plugin_is_block_theme() {
  return function_exists( 'wp_is_block_theme' ) && wp_is_block_theme();
}

if ( my_plugin_is_block_theme() ) {
  // Register custom blocks
  add_action( 'init', 'my_plugin_register_block' );
} else {
  // Use classic approach with hooks
  add_action( 'wp_footer', 'my_plugin_add_widget' );
}

Designing for Plugin Compatibility

When designing plugins for FSE, follow these compatibility principles:

Provide blocks instead of PHP output. Rather than hooking into wp_footer() or wp_head(), register custom blocks that site builders can add to templates. This works with both block and classic themes through the block editor. Blocks provide site editors with explicit control over where your plugin's content appears, whereas hooks can lead to unexpected behavior if the theme doesn't call them in expected locations or if multiple plugins hook into the same action, creating ordering conflicts.

Use theme.json for styling. Instead of enqueuing custom CSS with hardcoded colors and spacing, allow site builders to customize appearance through theme.json. This respects site-wide styling decisions and provides consistency. When your plugin blocks use theme.json colors and spacing, site builders can maintain visual cohesion across their entire site. A site redesign that updates theme.json automatically updates your plugin's appearance without requiring any code changes.

Avoid theme-specific assumptions. Don't assume the theme has a sidebar, specific template structure, or particular hooks. Build plugins that work independently. This principle is especially important when transitioning from classic theme development. Many classic plugins assume sidebars exist and try to register widgets. Block themes may not have sidebars at all, rendering that approach obsolete. Instead, make sidebar support optional and provide alternative mechanisms for displaying plugin content.

Support block visibility controls. FSE includes built-in responsive design and visibility controls. Support these features in your custom blocks rather than implementing your own. WordPress provides native attributes for controlling block visibility on different devices and to different user types. Using these built-in features ensures consistency and prevents your plugin from duplicating functionality.

Document compatibility requirements. Clearly state whether your plugin works with classic themes, block themes, or both. If there are specific requirements (like particular hooks or template structure), document them. Clear documentation helps site builders understand what to expect and reduces support requests from incompatible combinations.

/**
 * Plugin Name: My FSE Plugin
 * Description: Adds custom testimonial blocks
 * Requires: WordPress 6.0
 * Requires PHP: 7.4
 *
 * Compatibility:
 * - Works with block themes (recommended)
 * - Fallback support for classic themes
 * - Requires Gutenberg plugin for WordPress < 6.0
 */

Ensure Your Plugins Work with Modern WordPress

FSE compatibility is essential for future-proof WordPress development. WP HealthKit analyzes your plugin code and identifies FSE compatibility issues before users report problems.

Audit Your Plugin

Template Parts and Global Styles

Template parts are reusable block compositions that appear across multiple templates. Your site's header, footer, sidebar, and navigation might all be template parts. This architecture enables powerful reusability but requires careful design for plugin compatibility.

Template parts represent one of FSE's most powerful features for plugin developers. Rather than plugins hooking into scattered locations hoping the theme calls the right hooks, template parts allow plugins to provide self-contained components that site builders can place anywhere. A testimonial block plugin could provide a testimonial template part that appears in headers, footers, sidebars, or anywhere else on the page. The same block, the same configuration, rendered consistently everywhere it appears.

The global styles system in FSE takes this reusability further by allowing site-wide styling rules that apply to all instances of a block. If a site builder changes the color of all buttons through global styles, every button throughout the site—including those in your plugin's blocks—updates automatically. This creates a seamless, harmonious design experience that would be impossible to achieve with plugins that hardcode styling.

When your plugin needs to appear in multiple places (like a widget area), use template parts:

function my_plugin_register_template_part() {
  register_block_pattern_category( 'my-plugin', array(
    'label' => __( 'My Plugin Patterns' ),
  ) );

  register_block_pattern(
    'my-plugin/footer-widget',
    array(
      'title'       => __( 'Footer Widget' ),
      'description' => __( 'A footer widget for my plugin' ),
      'categories'  => array( 'my-plugin' ),
      'content'     => '<!-- wp:my-plugin/widget --><!-- /wp:my-plugin/widget -->',
    )
  );
}

add_action( 'init', 'my_plugin_register_template_part' );

Global Styles provide site-wide styling configuration. If your plugin provides custom blocks, register default styles that respect global style settings:

function my_plugin_render_block( $attributes, $content ) {
  $classes = array( 'my-plugin-block' );

  // Respect global style settings
  if ( isset( $attributes['textColor'] ) ) {
    $classes[] = 'has-' . $attributes['textColor'] . '-color';
  }

  if ( isset( $attributes['backgroundColor'] ) ) {
    $classes[] = 'has-' . $attributes['backgroundColor'] . '-bg';
  }

  $html = '<div class="' . esc_attr( implode( ' ', $classes ) ) . '">';
  $html .= wp_kses_post( $content );
  $html .= '</div>';

  return $html;
}

Additional Resources

For a comprehensive view of how WP HealthKit approaches plugin analysis, explore our 17 verification layers or browse the plugin directory to see real audit scores. Ready to check your own plugin? Run a free audit now.

Frequently Asked Questions

Will my classic WordPress plugin work with FSE sites?

Maybe. If your plugin hooks into template files or relies on specific template structure, it likely won't work well with block themes. However, plugins that register custom post types, provide admin interfaces, or implement REST API endpoints typically work fine. Review your plugin's dependencies and test it thoroughly with both classic and block themes.

What's the best way to migrate a classic plugin to support FSE?

Start by identifying what your plugin does: Does it add output to the frontend? Register custom post types? Modify the admin interface? For frontend output, convert it to custom blocks that site builders can add to templates. Maintain backward compatibility with classic themes by supporting both approaches if possible.

Should I require block themes for my new plugin?

Not necessarily. Block themes are powerful but not universal. Requiring block themes limits your potential audience. Instead, design your plugin to work well with both architectures. Use feature detection (wp_is_block_theme()) to adapt behavior based on the active theme.

How do I handle backward compatibility with classic themes?

Provide both approaches: register custom blocks for block themes, and implement hook-based output for classic themes. Detect the active theme and use the appropriate approach. This maximizes compatibility while taking advantage of FSE where available.

Can I add custom settings to theme.json?

Yes, use WP_Theme_JSON_Resolver::get_theme_data() to register custom settings. Your custom blocks can expose settings through theme.json, allowing site builders to configure them through the global styles interface rather than individual blocks.

What should I do if my plugin needs to appear in every template?

Create a template part that site builders can add to their templates. Provide a block pattern they can use to insert your plugin into new templates. This gives site builders control while making it easy to add your plugin's functionality.

Conclusion

WordPress full site editing plugin compatibility is essential for modern WordPress development. As FSE adoption grows, plugins that only work with classic themes will become increasingly marginalized. By understanding FSE architecture, supporting both block and classic themes where possible, and designing plugins to work with the block editor rather than against it, you future-proof your plugins for the WordPress ecosystem.

The key is thinking in terms of blocks and templates rather than PHP and hooks. Provide custom blocks for functionality, use theme.json for styling, and respect the site builder's control over templates. This approach creates plugins that work seamlessly in modern WordPress sites while maintaining backward compatibility.

WP HealthKit analyzes your plugin code for FSE compatibility issues and provides specific recommendations for improvement. Start auditing your plugins today to ensure they're ready for modern WordPress.

Check FSE Compatibility

WordPress Full Site Editing: Plugin Compatibility Guide

Table of Contents