Chapitre 6.4 — Charger CSS & JS (enqueue)

⏱️ TL;DR — On ne met jamais un <link> ou un <script> en dur dans un thème/plugin. On enregistre ses assets avec wp_enqueue_style() / wp_enqueue_script() sur le hook wp_enqueue_scripts (front) ou admin_enqueue_scripts (admin). Ce système gère les dépendances (ordre), les versions (cache-busting), le placement (<head> ou pied), et évite les doublons (jQuery chargé une seule fois). Pour passer des données PHP au JS, on utilise wp_localize_script() / wp_add_inline_script(). C’est la manière propre et obligatoire.

🎯 Objectifs

Enregistrer CSS/JS proprement avec les fonctions d’enqueue.
Gérer dépendances, versions et placement.
Passer des données de PHP vers JS en sécurité.
Charger conditionnellement (perf) et éviter les pièges.

1. Pourquoi pas de `<script>` en dur ?

Un <script src="…"> écrit en dur dans un template :

court-circuite la gestion des dépendances (votre JS s’exécute peut-être avant jQuery) ;
crée des doublons (deux plugins chargent la même lib deux fois) ;
empêche le cache-busting par version ;
ignore les hooks (wp_head/wp_footer) → cassable et non désactivable par les autres.

Le système d’enqueue résout tout ça. C’est obligatoire pour un code de qualité (et exigé pour publier sur wp.org, Partie 11).

2. Enqueue de base


add_action( 'wp_enqueue_scripts', 'montheme_assets' );
function montheme_assets() {
    // CSS
    wp_enqueue_style(
        'montheme-main',                                   // handle unique
        get_stylesheet_directory_uri() . '/assets/main.css',
        array(),                                           // dépendances
        wp_get_theme()->get( 'Version' )                   // version (cache-busting)
    );
 
    // JS
    wp_enqueue_script(
        'montheme-app',                                    // handle
        get_stylesheet_directory_uri() . '/assets/app.js',
        array( 'jquery' ),                                 // dépend de jQuery
        wp_get_theme()->get( 'Version' ),
        true                                               // dans le pied de page
    );
}

Handle : identifiant unique (préfixé). Sert aux dépendances et à éviter les doublons.
Dépendances : tableau de handles à charger avant (WordPress ordonne).
Version : ajoutée en query string (?ver=1.0.0) → force le rechargement quand elle change.
in_footer (5ᵉ arg JS) : true = juste avant </body> (recommandé pour ne pas bloquer le rendu).

⚠️ Piège n°1 — la version false/vide. Sans version, le navigateur peut servir une ancienne version en cache après un déploiement. Mettez toujours une version (celle du thème, ou un hash/filemtime). En dev, filemtime($chemin) garantit un cache-bust à chaque modification.

3. Register vs enqueue

wp_register_style/script : déclare un asset (handle + source + deps) sans le charger.
wp_enqueue_style/script : charge l’asset (et l’enregistre si besoin).

On enregistre une lib partagée une fois, puis on l’enqueue là où on en a besoin (éventuellement dans plusieurs contextes). wp_enqueue_script('handle') (handle déjà enregistré) suffit alors à la charger.

4. Passer des données de PHP vers JS

Votre JS a souvent besoin de valeurs PHP (URL de l’API, nonce de sécurité, chaînes traduites) :


wp_localize_script( 'montheme-app', 'MonThemeData', array(
    'ajaxUrl' => admin_url( 'admin-ajax.php' ),
    'restUrl' => esc_url_raw( rest_url( 'monplugin/v1/' ) ),
    'nonce'   => wp_create_nonce( 'wp_rest' ),
) );

Côté JS, un objet global MonThemeData est disponible (MonThemeData.restUrl, MonThemeData.nonce). Alternative moderne : wp_add_inline_script() pour injecter un script avant/après, ou l’API @wordpress/api-fetch (Partie 8/9) qui gère le nonce automatiquement.

⚠️ Piège n°2 — les secrets côté client. Tout ce que vous passez au JS est visible dans la page. N’y mettez jamais de clé d’API privée ou de secret : uniquement des URLs publiques et des nonces (jetons à usage limité, Partie 7). Le nonce autorise une action précise sans exposer de secret durable.

💡 Pour un dev React — wp_localize_script = injecter des variables d’environnement publiques (façon NEXT_PUBLIC_*) et un jeton dans le bundle client. Pour vos blocs Gutenberg (Partie 8), vous ferez mieux : @wordpress/scripts génère un fichier .asset.php qui déclare automatiquement les dépendances (wp-element, wp-blocks…) et une version basée sur le hash — le pipeline d’enqueue moderne, proche d’un build front classique.

5. Charger au bon endroit (perf)

Ne chargez pas tout partout. Conditionnez :


function montheme_assets() {
    wp_enqueue_style( 'montheme-main', /* … */ );        // partout
    if ( is_singular( 'livre' ) ) {                      // seulement sur un "livre"
        wp_enqueue_script( 'montheme-livre', /* … */ );
    }
}

Front : hook wp_enqueue_scripts.
Admin : hook admin_enqueue_scripts (et ne chargez que sur vos écrans, via le paramètre $hook).
Éditeur de blocs : enqueue_block_editor_assets (Partie 8).

⚠️ Piège n°3 — tout charger en admin. Enqueue sur admin_enqueue_scripts sans vérifier l’écran charge vos assets sur toutes les pages d’admin (et peut casser d’autres écrans). Vérifiez $hook (ou le contexte) pour ne charger que là où c’est utile.

✏️ Exercices

Pourquoi ne jamais écrire un <script src> en dur dans un template ?
Écrivez l’enqueue d’un app.js dépendant de jQuery, chargé dans le pied de page, versionné.
Vous devez passer l’URL de votre endpoint REST et un nonce au JS. Comment, et que ne faut-il pas y mettre ?

✅ Solution

Parce qu’un <script> en dur ignore la gestion des dépendances (ordre), crée des doublons, empêche le cache-busting par version et contourne les hooks — code fragile et non maintenable. L’enqueue résout tout cela.


wp_enqueue_script( 'montheme-app', get_stylesheet_directory_uri().'/assets/app.js',
  array( 'jquery' ), wp_get_theme()->get('Version'), true );

Via wp_localize_script() (ou wp_add_inline_script), en exposant l’URL REST et un nonce (wp_create_nonce('wp_rest')). On n’y met jamais de clé/secret privé : tout est visible côté client ; seuls URLs publiques et nonces sont acceptables.

🧠 Quiz de révision

1. Quelle fonction charge une feuille de style proprement ?

wp_enqueue_style() (sur le hook wp_enqueue_scripts).

2. À quoi sert le handle d’un asset ?

C’est son identifiant unique : il gère les dépendances et évite les doublons.

3. Pourquoi versionner ses assets ?

Pour le cache-busting : changer la version force le navigateur à recharger le fichier après un déploiement.

4. Comment passer des données PHP au JS ?

Avec wp_localize_script() (ou wp_add_inline_script), en n’exposant jamais de secret — seulement URLs publiques et nonces.

5. Quel hook pour charger des assets côté admin ?

admin_enqueue_scripts (en vérifiant l’écran $hook pour ne charger que là où c’est utile).

Chapitre suivant : Créer un thème bloc (FSE).