# Bien enqueuer scripts et styles avec WordPress : le guide complet

> Hook wp_enqueue_scripts, dépendances, versioning, wp_localize_script, chargement conditionnel : tout pour charger vos assets proprement.

- Auteur : Clément Hadrot
- Publié le : 2020-09-08
- Mis à jour le : 2020-09-08
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/enqueue-scripts-styles-wordpress/

## L’essentiel

- wp_enqueue_scripts est le seul hook fiable pour charger vos assets front
- Le versioning basé sur filemtime casse le cache à chaque modification
- wp_localize_script transmet des données PHP au JavaScript sans code en dur

WordPress 5.5 vient tout juste de sortir, avec son lot de nouveautés bienvenues : sitemaps XML natifs, lazy-loading natif des images grâce à l'attribut `loading="lazy"`, et mises à jour automatiques des plugins et thèmes. Mais une chose ne change pas depuis des années : la bonne méthode pour charger un fichier CSS ou JavaScript dans un thème reste `wp_enqueue_style()` et `wp_enqueue_script()`. Pourtant, on voit encore trop souvent des `<script>` codés en dur dans `header.php`.

Charger ses assets « à la main » casse la gestion des dépendances, empêche WordPress de détecter les doublons entre plugins et thème, et complique la purge du cache navigateur. Cet article détaille la bonne façon de faire, du hook de base jusqu'au chargement conditionnel avancé.

## Le hook wp_enqueue_scripts, votre unique point d'entrée

Tout enqueue de script ou de style côté public doit passer par le hook `wp_enqueue_scripts`, jamais directement dans le corps d'un fichier de gabarit. Voici la structure de base à reproduire dans `functions.php` ou, mieux, dans un fichier `inc/enqueue.php` dédié :

```
<?php
add_action( 'wp_enqueue_scripts', 'wpm_charger_assets' );

function wpm_charger_assets() {
    wp_enqueue_style(
        'wpm-style',
        get_stylesheet_uri(),
        array(),
        wp_get_theme()->get( 'Version' )
    );

    wp_enqueue_script(
        'wpm-main',
        get_template_directory_uri() . '/assets/js/main.js',
        array( 'jquery' ),
        wp_get_theme()->get( 'Version' ),
        true
    );
}
```

Le dernier paramètre `true` de `wp_enqueue_script()` place le script juste avant la fermeture de `</body>` plutôt que dans `<head>`, ce qui évite de bloquer le rendu de la page pendant le téléchargement du fichier.

## Gérer les dépendances intelligemment

> L'essentiel à retenir : wp_enqueue_scripts est le seul hook fiable pour charger vos assets front ; Le versioning basé sur filemtime casse le cache à chaque modification ; wp_localize_script transmet des données PHP au JavaScript sans code en dur

Le troisième paramètre de `wp_enqueue_script()` accepte un tableau de « handles », c'est-à-dire les identifiants d'autres scripts déjà enregistrés dont le vôtre dépend. C'est ce mécanisme qui garantit que `jquery` sera chargé avant `wpm-main`, même si un plugin enqueue également jQuery ailleurs sur la page : WordPress ne le chargera jamais deux fois.

Cette gestion automatique des dépendances est justement ce qu'on perd en insérant des balises `<script>` manuelles : aucune garantie d'ordre, aucune déduplication, et un risque réel de conflit avec les scripts des plugins actifs.

## Le versioning pour maîtriser le cache navigateur

Le quatrième paramètre de `wp_enqueue_style()` et `wp_enqueue_script()` définit un numéro de version, ajouté automatiquement en suffixe de l'URL du fichier (`?ver=1.0.0`). Cette chaîne sert de « cache buster » : tant qu'elle ne change pas, le navigateur peut réutiliser sa copie en cache du fichier.

En développement, je recommande une astuce simple pour ne plus jamais avoir à vider son cache manuellement : utiliser la date de modification du fichier comme version.

```
<?php
wp_enqueue_script(
    'wpm-main',
    get_template_directory_uri() . '/assets/js/main.js',
    array( 'jquery' ),
    filemtime( get_template_directory() . '/assets/js/main.js' ),
    true
);
```

`filemtime()` renvoie l'horodatage de dernière modification du fichier : à chaque sauvegarde, la version change automatiquement, et le navigateur du client recharge le fichier à jour. Sur un environnement de production à fort trafic, préférez toutefois un numéro de version fixe lié à votre changelog, pour éviter un appel disque à chaque chargement de page.

## Transmettre des données PHP au JavaScript avec wp_localize_script

Il arrive souvent qu'un script JavaScript ait besoin d'informations générées côté PHP : l'URL d'`admin-ajax.php`, un nonce de sécurité, ou une chaîne traduite. `wp_localize_script()` résout ce besoin proprement, sans jamais écrire de PHP en dur dans un fichier `.js` :

```
<?php
wp_enqueue_script( 'wpm-ajax', get_template_directory_uri() . '/assets/js/ajax.js', array( 'jquery' ), '1.0.0', true );

wp_localize_script( 'wpm-ajax', 'wpmData', array(
    'ajaxUrl' => admin_url( 'admin-ajax.php' ),
    'nonce'   => wp_create_nonce( 'wpm_ajax_nonce' ),
) );
```

Côté JavaScript, l'objet `wpmData` devient directement accessible, avec `wpmData.ajaxUrl` et `wpmData.nonce` prêts à l'emploi dans votre appel `fetch()` ou `jQuery.ajax()`.

## Charger un script uniquement là où il sert

Enqueuer un script sur toutes les pages alors qu'il ne sert que sur le formulaire de contact gaspille de la bande passante et ralentit inutilement le site. Les fonctions conditionnelles de WordPress permettent de cibler précisément :

- `is_page( 'contact' )` pour une page précise
- `is_single()` pour tous les articles
- `is_front_page()` pour la page d'accueil uniquement

```
<?php
function wpm_charger_assets_contact() {
    if ( is_page( 'contact' ) ) {
        wp_enqueue_script( 'wpm-contact', get_template_directory_uri() . '/assets/js/contact.js', array(), '1.0.0', true );
    }
}
add_action( 'wp_enqueue_scripts', 'wpm_charger_assets_contact' );
```

> Sur mes derniers projets, ce simple chargement conditionnel a fait gagner entre 15 et 20 % de poids JavaScript sur les pages qui n'en avaient pas besoin. Un gain minime page par page, mais qui compte vraiment sur la note globale de performance.

## En résumé

Passer systématiquement par `wp_enqueue_style()` et `wp_enqueue_script()`, coupler ces appels à un versioning intelligent et charger les scripts uniquement là où ils sont utiles : voilà les trois piliers d'une gestion d'assets propre sous WordPress. Avec l'arrivée du lazy-loading natif dans WP 5.5, la performance côté images progresse toute seule ; c'est justement le bon moment pour faire le même effort côté scripts et styles.
