npx @wordpress/env start lance un environnement WordPress complet en quelques minutes, mais seulement si le fichier .wp-env.json qui le décrit est complet et versionné avec le reste du projet — sans quoi chaque développeur reconstruit sa propre configuration à la main, avec ses propres extensions activées et ses propres réglages, jamais identiques à ceux d’un collègue.
wp-env est l’outil officiel maintenu par l’équipe WordPress pour lancer un environnement de développement local reposant sur Docker, sans configuration manuelle de conteneurs. Sa force réside précisément dans le fichier .wp-env.json, qui décrit intégralement l’environnement souhaité — version de WordPress, extensions et thèmes montés, ports exposés — permettant à quiconque clone le dépôt de reproduire exactement le même environnement en une seule commande.
La structure d’un fichier .wp-env.json complet
Pour un projet d’agence classique développant un thème et une extension personnalisée, le fichier prend une forme proche de celle-ci :
{
"core": "WordPress/WordPress#6.6",
"phpVersion": "8.2",
"plugins": [
"./extension-personnalisee",
"https://downloads.wordpress.org/plugin/query-monitor.zip"
],
"themes": [
"./theme-personnalise"
],
"config": {
"WP_DEBUG": true,
"WP_DEBUG_LOG": true
},
"port": 8888,
"env": {
"tests": {
"port": 8889
}
}
}Chaque champ correspond à une décision explicite plutôt qu’implicite : la version exacte de WordPress fixée par un identifiant de commit ou de version, la version de PHP alignée sur celle du serveur de production, les extensions de développement comme Query Monitor incluses systématiquement pour tous les développeurs du projet.
Ce que ce versionnage supprime concrètement
Sans ce fichier versionné, chaque développeur configure son environnement local selon sa propre mémoire du projet ou selon une documentation qui vieillit mal. Les divergences qui en résultent sont souvent invisibles jusqu’au jour où un bug ne se reproduit que sur le poste d’une seule personne, faute d’une extension de débogage installée ailleurs, ou d’une version de PHP différente d’un poste à l’autre.
- Une seule commande,
npx @wordpress/env start, reconstruit l’environnement complet - La version de WordPress et de PHP est fixée dans le fichier, jamais laissée au hasard de l’installation locale
- Les extensions de développement communes à toute l’équipe sont incluses automatiquement
Séparer l’environnement de développement et l’environnement de test
Le champ env du fichier permet de définir des variantes de configuration pour des contextes distincts, ici un environnement dédié à l’exécution des tests automatisés sur un port différent de celui utilisé pour le développement quotidien. Cette séparation évite qu’une session de tests automatisés ne perturbe l’environnement de développement en cours d’utilisation sur le même poste.
Ce qui reste propre à chaque poste malgré tout
Le fichier .wp-env.json versionné décrit l’environnement partagé par toute l’équipe, mais certains réglages restent légitimement propres à chaque poste — un port différent si celui par défaut est déjà occupé localement, par exemple. wp-env permet de surcharger localement certains réglages via un fichier .wp-env.override.json non versionné, qui complète sans remplacer la configuration commune.
Reproduire un environnement sur un nouveau poste
Sur un nouveau poste de travail, cloner le dépôt du projet, installer les dépendances Node.js nécessaires puis lancer npx @wordpress/env start suffit à obtenir un environnement identique à celui de tous les autres membres de l’équipe, sans configuration manuelle supplémentaire. Ce délai, mesuré sur plusieurs onboardings récents, avoisine cinq minutes une fois les images Docker déjà téléchargées, contre plusieurs heures de configuration manuelle et de comparaison avec un collègue auparavant.
Ce que ce fichier ne couvre pas
Ce fichier décrit l’environnement de développement local ; il ne remplace pas la gestion des accès et des identifiants transmis à une nouvelle recrue, ni la formation aux conventions propres au projet, deux sujets distincts qui accompagnent naturellement la mise en place de cet environnement sans s’y substituer.
En résumé
Un fichier .wp-env.json versionné avec le reste du projet transforme la configuration d’un environnement de développement local d’une source récurrente de divergences en une commande unique et reproductible pour toute l’équipe. Le coût de rédaction initial reste minime, et le bénéfice se ressent à chaque nouvelle recrue ou chaque changement de poste de travail, sans jamais avoir à redécouvrir la configuration attendue.
