Un starter thème bloc d’agence : structure de dépôt, build et conventions

Après avoir démarré plusieurs thèmes blocs from scratch, chacun réinventant sa propre organisation de dossiers, nous avons pris le temps de figer un starter thème maison. L’objectif n’était pas de créer un framework generique de plus, mais de capitaliser sur les décisions structurelles qui reviennent identiques sur chaque nouveau projet client, pour ne plus les reprendre depuis zéro à chaque fois.

Ce starter a servi de base à six projets en un an, du site vitrine simple à une plateforme de mise en relation avec des types de contenus personnalisés. Voici les choix qui le composent, et pourquoi.

Arborescence générale

starter-theme/
  theme.json
  functions.php
  templates/
    index.html
    single.html
    page.html
    archive.html
  parts/
    header.html
    footer.html
  patterns/
    hero-accueil.php
    grille-services.php
  inc/
    setup.php
    blocks.php
    patterns.php
  assets/
    src/
      styles/
      scripts/
    build/
  styles/
    contraste-eleve.json

Le principe directeur : un fichier ne doit jamais être ambigu quant à son rôle rien qu’à son chemin. Le dossier inc/ sépare l’enregistrement technique (setup.php pour les support de thème, blocks.php pour les blocs personnalisés, patterns.php pour l’enregistrement centralisé des patterns) plutôt que de tout entasser dans un functions.php qui grossirait indéfiniment.

Compilation des assets

Le dossier assets/src/ contient les sources non compilées (Sass, JS avec modules), compilées vers assets/build/ via un script npm minimal basé sur @wordpress/scripts, l’outillage officiel maintenu par l’équipe cœur de WordPress pour les projets de blocs.

{
  "scripts": {
    "build": "wp-scripts build",
    "start": "wp-scripts start"
  },
  "devDependencies": {
    "@wordpress/scripts": "^27.0.0"
  }
}

Seul assets/build/ est chargé en production, jamais assets/src/. Cette séparation stricte évite qu’un développeur charge par erreur un fichier Sass non compilé sur un environnement client, une erreur que nous avions vue se produire sur un ancien projet sans cette convention.

Patterns critiques enregistrés en PHP

Contrairement à une approche tout-fichiers-HTML, nous enregistrons les patterns structurants (en-tête de section héros, grille de services) via register_block_pattern() en PHP plutôt qu’en simples fichiers déposés dans patterns/ avec des commentaires d’en-tête.

register_block_pattern( 'starter-theme/hero-accueil', array(
    'title'       => __( 'Héros accueil', 'starter-theme' ),
    'categories'  => array( 'starter-theme' ),
    'content'     => starter_theme_get_pattern_content( 'hero-accueil' ),
) );

Cette indirection via une fonction dédiée, starter_theme_get_pattern_content(), permet d’injecter dynamiquement des valeurs (comme l’année en cours dans un pattern de pied de page) sans dupliquer le contenu HTML brut à chaque projet client qui hérite du starter.

Un préfixe de nommage unique par projet

Chaque nouveau projet issu du starter renomme son préfixe de slug de thème (le texte-domain, les catégories de patterns, les classes CSS utilitaires) selon une convention fixe : [client]-theme. Ce choix évite les collisions quand un site migre plus tard vers une infrastructure multisite, ou quand un ancien thème client reste présent dans un environnement de test aux côtés d’un nouveau projet basé sur le même starter.

Élément	Convention
Text-domain	[client]-theme
Préfixe des fonctions PHP	[client]_theme_
Préfixe des slugs de presets	[client]-couleur-, [client]-espace-

Un starter thème n’a de valeur que si l’équipe entière l’utilise réellement. Le nôtre a d’abord échoué une première fois, laissé de côté parce que trop rigide sur la structure des patterns. La deuxième version, plus permissive sur ce point précis, a été adoptée sans résistance.

Ce que ce starter ne couvre pas

Cette architecture concerne uniquement la structure du thème lui-même : elle ne définit pas le pipeline de déploiement (intégration continue, environnements de recette, synchronisation de base de données entre environnements), qui reste un sujet distinct traité par nos outils d’agence indépendamment du thème.

En résumé

Un starter thème bloc d’agence gagne à rester simple sur les patterns et strict sur l’arborescence des fichiers techniques. Les six projets démarrés depuis cette base ont chacun nécessité moins d’une journée de mise en place initiale, contre plusieurs jours auparavant quand chaque thème repartait d’une organisation différente.