wp_register_script_module()

Définition : wp_register_script_module() enregistre un module JavaScript ES auprès de WordPress sans imposer son chargement immédiat. Elle déclare l’identité, la source et les dépendances nécessaires à l’API des modules.

Comprendre et utiliser

À quoi sert ce terme ?

Cette séparation facilite une architecture front-end moderne : les ressources sont connues du registre avant leur utilisation et peuvent être chargées uniquement là où une fonctionnalité est réellement présente.

Fonctionnement technique

La fonction reçoit un identifiant unique, une URL et des dépendances de modules, avec une version optionnelle. Le registre des modules est distinct du registre des scripts classiques géré par wp_register_script().

Dans quels contextes l’utiliser ?

Utiliser dans un plugin WordPress récent dont l’interface est construite avec des imports JavaScript natifs. Prévoir une vérification des versions minimales du Core pour cette API introduite avec WordPress 6.5.

Cas concret : ATOOLPHA

ATOOLPHA prépare un module « recherche avancée » présent seulement sur une page documentaire. Il peut être enregistré une fois et utilisé conditionnellement.

Exemple de code commenté

Extrait PHP destiné à un plugin ou à un template WordPress, dans le contexte indiqué ; pas au contenu HTML de l’article.

<?php
add_action( 'wp_enqueue_scripts', function () {
    wp_register_script_module(
        'atoolpha/search',
        plugin_dir_url( __FILE__ ) . 'assets/search.js',
        array(), '1.0.0'
    );
    if ( is_page( 'recherche-technique' ) ) {
        wp_enqueue_script_module( 'atoolpha/search' );
    }
} );

Décryptage de l’exemple

Le module est identifié par atoolpha/search et son URL suppose un vrai fichier assets/search.js dans le plugin. La condition limite l’usage à une page donnée. Le code nécessite une version de WordPress prenant en charge la Script Modules API.

Résultat attendu

Le module est enregistré pour la requête et chargé sur la page ciblée ; les autres pages n’ont pas à recevoir ce script.

Exercice pratique et vérification

Enregistrer le module, le charger sur une page de test puis inspecter la balise type=module et les erreurs réseau. Vérifier son absence sur une autre page.

Précautions et limites

Les imports ES, dépendances, URL et versions doivent être cohérents. Ne pas mélanger arbitrairement les tableaux de dépendances des modules avec ceux des scripts classiques.

À ne pas confondre

wp_register_script_module() enregistre ; wp_enqueue_script_module() demande un chargement ; wp_register_script() cible le système de scripts classiques.

Diagnostic avancé

Si un import ES échoue, consulter la carte d’importation, l’ID du module et les URLs des dépendances plutôt que de remplacer module par un script traditionnel sans analyse.

Choix d’architecture et déploiement

Une architecture modulaire demande un choix cohérent des outils de build. Les fichiers sources ne doivent pas être confondus avec les assets effectivement livrés : identifier le point d’entrée, les imports et l’URL de déploiement fait partie de la vérification d’une extension.