/wp-plugin-theme

description: Declare plugin dependencies and generate plugin-specific CSS and compatibility code for a block theme.

/wp-plugin-theme

**Purpose:** Extend a block theme to declare plugin dependencies, add plugin-specific CSS stubs, and generate compatibility code for the most common WordPress plugins (Yoast SEO, WPForms, Gravity Forms, ACF, Jetpack, WooCommerce, and others).

Trigger

User types `/wp-plugin-theme` OR asks for plugin compatibility in their theme, OR their conversion source HTML references plugin output (e.g., a contact form, SEO breadcrumbs, a review widget).

Workflow

Step 1: Identify Plugins

Ask (or infer from source HTML / context):

| Question | Why it matters | |----------|---------------| | Which plugins are **required** (theme breaks without them)? | Go into `required_plugins` declaration | | Which plugins are **recommended** (optional features)? | Go into `recommended_plugins` declaration | | Which plugins is the user already using? | Determines which CSS stubs to generate | | Any page builder plugins (Elementor, Divi)? | Different compatibility approach |

**Common plugins to ask about:**

• Yoast SEO / Rank Math / SEOPress (breadcrumbs, OG tags)
• WPForms / Gravity Forms / Contact Form 7 (forms)
• ACF / CMB2 / Meta Box (custom fields)
• WooCommerce (eCommerce — use `/convert-to-wp-theme` + `references/woocommerce.md` instead for full WooCommerce themes)
• Jetpack (social sharing, related posts)
• WP Rocket / LiteSpeed Cache (caching plugins)
• Yoast Duplicate Post / WP All Import (content tools)
• TranslatePress / Polylang / WPML (translation)
• The Events Calendar (events)
• MemberPress / Restrict Content Pro (membership)

Step 2: Produce a Plugin Compatibility Plan

PLUGIN COMPATIBILITY PLAN
==========================
| Plugin              | Status      | What theme generates                              |
|---------------------|-------------|--------------------------------------------------|
| Yoast SEO           | Required    | Breadcrumb template part, OG image size, CSS stub |
| WPForms             | Required    | Form CSS stub, accessibility overrides            |
| ACF                 | Required    | Block Bindings source, post meta registration     |
| Gravity Forms       | Recommended | CSS stub, AJAX compat note                        |
| Jetpack             | Recommended | CSS stub for sharing buttons                      |

Show plan, get confirmation before generating files.

Step 3: Plugin Dependency Declaration

WordPress 6.5+ supports declaring required plugins in `style.css` header. Additionally use the TGMPA pattern for backward compatibility.

**style.css header addition:**

/*
 * Theme Name:   {{Theme Name}}
 * ...
 * Requires Plugins: {{plugin-slug}}, {{plugin-slug-2}}
 */

Slugs must match the plugin's **WordPress.org directory slug** — the folder name under `wp-content/plugins/`. For example, WPForms is `wpforms-lite` (free) or `wpforms` (pro); ACF is `advanced-custom-fields` (free) or `advanced-custom-fields-pro` (pro). Verify slugs at `wordpress.org/plugins/{{slug}}` before committing.

> **ACF Block Bindings version requirement:** Using ACF fields with the Block Bindings API requires **ACF PRO 6.3+** (for native binding support) or the custom `register_block_bindings_source()` approach shown in `commands/wp-migrate.md`. The Block Bindings API itself requires **WordPress 6.5+**. Always check both version constraints before declaring ACF as a required plugin for binding-dependent features.

**TGMPA-style helper in `inc/plugin-dependencies.php`:**

<?php
/**
 * Plugin dependency declarations.
 *
 * Note: WordPress 6.5+ reads "Requires Plugins" from style.css header.
 * This file provides a user-facing admin notice for older WP versions
 * and for plugins not on WordPress.org.
 */
function {{theme_slug_underscored}}_check_plugin_dependencies(): void {
    if ( ! is_admin() ) {
        return;
    }

    $required = array(
        array(
            'slug'    => '{{plugin-slug}}',
            'name'    => '{{Plugin Name}}',
            'version' => '{{min-version}}',
        ),
    );

    $missing = array();
    foreach ( $required as $plugin ) {
        if ( ! is_plugin_active( $plugin['slug'] . '/' . $plugin['slug'] . '.php' )
            && ! is_plugin_active( $plugin['slug'] . '/index.php' ) ) {
            $missing[] = $plugin['name'] . ' (v' . $plugin['version'] . '+)';
        }
    }

    if ( ! empty( $missing ) ) {
        add_action( 'admin_notices', function() use ( $missing ) {
            printf(
                '<div class="notice notice-error"><p>%s</p></div>',
                sprintf(
                    /* translators: %s: list of required plugins */
                    esc_html__( '{{Theme Name}} requires the following plugins: %s', '{{text-domain}}' ),
                    '<strong>' . esc_html( implode( ', ', $missing ) ) . '</strong>'
                )
            );
        } );
    }
}
add_action( 'admin_init', '{{theme_slug_underscored}}_check_plugin_dependencies' );

Add to `functions.php`:

require_once get_template_directory() . '/inc/plugin-dependencies.php';

Step 4: Generate Per-Plugin Compatibility Code

Output only the files relevant to the plugins identified in Step 1.

---

Yoast SEO / Rank Math / SEOPress

**Breadcrumb template part** (`parts/breadcrumbs.html`):

<!-- wp:group {"tagName":"nav","ariaLabel":"Breadcrumb","className":"site-breadcrumbs","layout":{"type":"constrained"}} -->
<nav class="wp-block-group site-breadcrumbs" aria-label="<?php esc_attr_e( 'Breadcrumb', '{{text-domain}}' ); ?>">
    <!-- wp:html -->
    <?php
    if ( function_exists( 'yoast_breadcrumb' ) ) {
        yoast_breadcrumb( '<p class="breadcrumb">', '</p>' );
    } elseif ( function_exists( 'rank_math_the_breadcrumbs' ) ) {
        rank_math_the_breadcrumbs();
    } elseif ( function_exists( 'seopress_display_breadcrumbs' ) ) {
        se