Skip to content

Conversation

a6uzar
Copy link

@a6uzar a6uzar commented Jul 24, 2025

Fixes #70873

Implements an allowlist-based filtering system for the Interactivity API Router to only load JavaScript modules of interactive blocks during client-side navigation.

Changes:

  • Add allowlist patterns for interactive block modules
  • Implement server-side PHP integration for allowlist configuration
  • Add WordPress filter hooks for plugin extensibility
  • Include comprehensive test coverage
  • Update documentation with usage examples

The solution prevents loading unnecessary JavaScript modules, improving performance and preventing potential conflicts during navigation.

What?

Closes #70873

This PR implements a selective module loading system for the Interactivity API Router that only loads JavaScript modules belonging to interactive blocks during client-side navigation, instead of loading all script modules found in the HTML.

Why?

The current implementation of the Interactivity API Router loads ALL JavaScript modules from the HTML during client-side navigation, including potentially unnecessary ones that aren't related to interactive blocks or compatible with the Interactivity API. This causes:

  • Performance issues: Unnecessary JavaScript execution during navigation
  • Potential conflicts: Loading code that may not be compatible with the Interactivity API
  • Resource waste: Loading modules that aren't needed for the interactive functionality

How?

The solution implements a multi-layered filtering approach:

  1. Pattern-based detection: Automatically identifies interactive block modules using patterns like @wordpress/block-library/*/view, @wordpress/interactivity*
  2. Explicit allowlist: Supports manually configured module IDs via PHP filter hooks
  3. Server-side integration: PHP function generates allowlist configuration that gets passed to the frontend
  4. Plugin extensibility: WordPress filter gutenberg_interactive_module_allowlist allows plugins to register their interactive modules

Key changes:

  • Modified preloadScriptModules() in script-modules.ts to filter modules through isInteractiveBlockModule()
  • Added PHP integration in client-assets.php for server-side allowlist generation
  • Created initialization system to read allowlist configuration from the DOM
  • Added comprehensive test coverage for the filtering logic

Testing Instructions

Manual Testing:

  1. Set up a WordPress environment with Gutenberg plugin active
  2. Create a page with multiple interactive blocks (e.g., Search block, Navigation block)
  3. Add some non-interactive blocks and custom plugins with script modules
  4. Enable browser DevTools Network tab
  5. Navigate between pages using client-side navigation
  6. Verify that only interactive block modules are loaded during navigation

Plugin Developer Testing:

  1. Create a custom plugin with interactive blocks
  2. Register your modules using the PHP filter:
    add_filter('gutenberg_interactive_module_allowlist', function($allowlist) {
        $allowlist[] = '@my-plugin/interactive-block/view';
        return $allowlist;
    });
    
    Unit Testing:
    npm test [script-modules-allowlist.test.ts](http://_vscodecontentref_/0)
    
    Testing Instructions for Keyboard

This change doesn't affect the user interface directly - it's a performance optimization for module loading during navigation. Keyboard navigation should work exactly the same as before, but with improved performance. Test by:

Use keyboard navigation (Tab, Enter, Arrow keys) to navigate through interactive blocks
Navigate between pages using keyboard shortcuts
Verify all interactive functionality remains accessible via keyboard

Fixes WordPress#70873

Implements an allowlist-based filtering system for the Interactivity API Router
to only load JavaScript modules of interactive blocks during client-side navigation.

Changes:
- Add allowlist patterns for interactive block modules
- Implement server-side PHP integration for allowlist configuration
- Add WordPress filter hooks for plugin extensibility
- Include comprehensive test coverage
- Update documentation with usage examples

The solution prevents loading unnecessary JavaScript modules, improving
performance and preventing potential conflicts during navigation.
@a6uzar a6uzar requested a review from spacedmonkey as a code owner July 24, 2025 07:32
Copy link

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @a6uzar.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: a6uzar.

Co-authored-by: DAreRodz <darerodz@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@github-actions github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Jul 24, 2025
Copy link

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @a6uzar! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

@t-hamano t-hamano added [Type] Enhancement A suggestion for improvement. [Package] Interactivity Router /packages/interactivity-router labels Jul 26, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository [Package] Interactivity Router /packages/interactivity-router [Type] Enhancement A suggestion for improvement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

iAPI Router: Only load modules of interactive blocks on client-side navigation
2 participants