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

> Comment nous avons structuré notre thème bloc de base maison : arborescence, compilation des assets, patterns en PHP et conventions de nommage des presets.

- Auteur : Clément Hadrot
- Publié le : 2024-08-15
- Mis à jour le : 2024-08-15
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/starter-theme-bloc-agence-architecture/

## L’essentiel

- Une arborescence pensée pour retrouver un fichier en moins de dix secondes
- Les patterns critiques sont enregistrés en PHP plutôt qu'en fichiers HTML seuls
- Un préfixe de nommage unique évite les collisions de presets entre projets

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.

> L'essentiel à retenir : Une arborescence pensée pour retrouver un fichier en moins de dix secondes ; Les patterns critiques sont enregistrés en PHP plutôt qu'en fichiers HTML seuls ; Un préfixe de nommage unique évite les collisions de presets entre projets

## 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.