Theme-Specific Custom Blocks — How to Bundle Theme

  • woracious

    (@woracious)


    1 month, 3 weeks ago

    I am developing a WordPress block theme that relies on a set of custom Gutenberg blocks built specifically for that theme. These are not general-purpose blocks that would be useful to the broader WordPress community — they are tightly coupled to the theme’s design, markup structure, and CSS. Examples include a theme-specific primary navigation block, a post listing block with AJAX load more that reads the theme’s data attributes, a post content block that renders within the theme’s markup conventions, and so on.

    I understand the WordPress.org guideline that blocks generally belong in plugin territory, and I respect the reasoning behind that separation. However, my situation raises a practical bundling question that I would appreciate clarity on.

    If I build these blocks directly within the theme folder (for instance, under a directory like our-block/src/ with a compiled our-block/build/ that registers the blocks via register_block_type in the theme’s functions.php), would this approach be accepted for a theme submission? The blocks serve no purpose outside the theme — they depend on the theme’s style sheet classes, template structure, and AJAX handlers that live in the theme’s inc/ directory. Extracting them into a standalone plugin would leave users with blocks that render broken markup if they switch to a different theme.

    Alternatively, if the expectation is that these must be developed as a separate companion plugin, I have a concern about the submission workflow. The plugin approval process on WordPress.org operates on its own timeline. If my theme depends on that plugin to function correctly, I cannot realistically submit the theme until the plugin is approved. And the plugin, being theme-specific, may not meet the general-utility expectation that plugin reviewers look for. This creates a circular dependency in the approval process — the theme needs the plugin, the plugin only makes sense with the theme, and neither can be submitted independently without the other being live.

    I would like to understand the recommended approach for this scenario. Specifically:

    1. Is bundling theme-specific custom blocks within the theme directory acceptable for a block theme submission, given that the blocks(and creating and distributing separate plugin) have no standalone utility?
    2. If a companion plugin is required, can the plugin be bundled within the theme directory during submission?
    3. If a companion plugin is required, is there an established workflow for submitting a theme and its dependent plugin in parallel so that both can be reviewed with full context?
    4. Are there any existing block themes in the directory that handle this pattern that I could reference as a precedent?

    I want to build this correctly from the outset rather than restructure after a rejection. Any guidance the team can provide would be greatly valued.

Viewing 2 replies - 1 through 2 (of 2 total)
  • Ravi Khadka

    (@ravikhadka)

    1 month, 3 weeks ago

    Hi,

    Yes, you can bundle custom Gutenberg blocks with your theme instead of using a separate plugin.

    Recommended approach:

    1. Register blocks inside the theme
      You can include your custom block code inside your theme folder (for example inside /inc/blocks/ or /blocks/).
    2. Use register_block_type()
      Register blocks from functions.php or a dedicated file:

    function mytheme_register_blocks() {
    register_block_type( get_template_directory() . ‘/blocks/your-block’ );
    }
    add_action( ‘init’, ‘mytheme_register_blocks’ );

    1. Enqueue block assets properly
      Make sure block scripts and styles are loaded using:
    • editor_script
    • editor_style
    • style

    inside block.json or register_block_type().

    1. Use block.json (recommended modern way)
      Create block using block.json structure. WordPress automatically handles asset loading and compatibility.
    2. Important note
      If the block is theme-specific (only for this theme), bundling inside theme is fine.
      If block should work after theme change, better keep it in plugin.

    Official reference:
    https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/

    Hope this helps 🙂

    Thread Starter woracious

    (@woracious)

    1 month, 3 weeks ago

    Your response misses the contention I raised.

Viewing 2 replies - 1 through 2 (of 2 total)

You must be logged in to reply to this topic.