Skip to content

README.md

Latest commit

 

History

History
264 lines (175 loc) · 9.69 KB

README.md

File metadata and controls

264 lines (175 loc) · 9.69 KB
Raw

Be API FrontEnd Framework

Be API Github Banner

Maintenance

Qu’est-ce que BFF ?

Be API Frontend Framework (ou BFF) est un boilerplate de thème WordPress conçu pour vous aider à lancer votre propre thème WordPress avec des outils modernes.

Prérequis

PHP et WordPress

  • PHP 8.3 ou supérieur
  • WordPress 6.3 ou supérieur

Composer

Composer est nécessaire pour autoloader toutes vos classes depuis le dossier inc.

Utilisez le package beapi/composer-scaffold-theme, qui l’ajoute automatiquement au fichier composer.json. Vous pouvez aussi l’ajouter vous-même ainsi :

    "autoload": {
        "psr-4": {
            "BEA\\Theme\\Framework\\": "content/themes/framework/inc/"
        }
    }

Autoload

L’autoload repose sur PSR-4 et est géré par Composer.

Node.js

Vous avez besoin de la dernière version stable de Node.js.

Installation

Téléchargez la dernière release de BFF ici et extrayez l’archive zip dans le dossier themes de WordPress.

|____wp-admin
|____wp-content
| |____plugins
| |____themes
| | |____beapi-frontend-framework
| |____uploads
|____wp-includes

Vous pouvez bien sûr renommer beapi-frontend-framework pour définir le nom de votre thème WordPress.

Ensuite, rendez-vous dans le dossier du thème (dans l’exemple ci-dessous, je n’ai pas renommé beapi-frontend-framework) avec votre terminal préféré.

cd wp-content/themes/beapi-frontend-framework

Puis installez les dépendances Node avec Yarn.

yarn

Vous pouvez aussi utiliser NPM.

npm install

Développement local avec wp-env

BFF inclut une configuration wp-env (.wp-env.json) pour exécuter une instance WordPress locale avec Docker.

Prérequis

Installation de wp-env

Vous pouvez lancer wp-env sans installation globale via npx @wordpress/env, ou installer la CLI une fois et utiliser la commande wp-env :

# Installation globale (npm ou yarn)
npm install -g @wordpress/env
# ou
yarn global add @wordpress/env

Après l’installation, remplacez npx @wordpress/env par wp-env dans les commandes ci-dessous.

Démarrage

Depuis la racine du thème :

yarn
npx @wordpress/env start
# ou, si wp-env est installé globalement :
wp-env start

Au premier démarrage, wp-env va :

  • Démarrer WordPress (PHP 8.3)
  • Monter ce thème depuis le répertoire courant
  • Installer et activer l’extension Advanced Custom Fields

URLs et identifiants
Site http://localhost:8888
Admin http://localhost:8888/wp-admin
Identifiant admin
Mot de passe password

Commandes courantes

# Démarrer l’environnement
npx @wordpress/env start   # ou : wp-env start

# Arrêter les conteneurs (les données sont conservées)
npx @wordpress/env stop    # ou : wp-env stop

# Supprimer conteneurs et volumes
npx @wordpress/env destroy # ou : wp-env destroy

# Exécuter WP-CLI dans l’environnement
npx @wordpress/env run cli wp plugin list
# ou : wp-env run cli wp plugin list

# Exécuter une commande dans le dossier du thème
npx @wordpress/env run cli --env-cwd=wp-content/themes/beapi-frontend-framework composer install
# ou : wp-env run cli --env-cwd=wp-content/themes/beapi-frontend-framework composer install

Workflow de développement

Avec wp-env en cours d’exécution, lancez le watcher Webpack dans un second terminal :

yarn start

Les changements sur les assets PHP, SCSS et JavaScript sont pris en compte après rebuild Webpack. Les modifications PHP du thème sont appliquées immédiatement grâce au volume monté.

Configuration

Les fichiers de configuration se trouvent dans le dossier config.

Webpack

Vous trouverez le fichier de paramètres Webpack communs dans webpack.common.js. Pour le mode développement, éditez webpack.dev.js ; pour la production, webpack.prod.js. Les loaders sont dans loaders.js et les plugins Webpack dans plugins.js.

Comment utiliser BFF ?

Après l’installation des dépendances, vous pouvez exécuter les commandes décrites ci-dessous.

Démarrer avec Browser Sync

BFF est configuré pour fonctionner avec Lando. Si vous avez un fichier .lando.yml à la racine de votre projet, indiquez le chemin vers ce fichier dans browsersync.config.js.

let fileContents = fs.readFileSync('../../../../.lando.yml', 'utf8')

Puis exécutez la commande suivante depuis le thème :

yarn start

BrowserSync proxifiera votre serveur Lando d’après le nom défini dans votre .lando.yml.

Build

yarn build

Rapport de bundle

Vous pouvez générer un rapport de bundle avec la commande suivante :

yarn bundle-report

Core Web Vitals

Ce que le thème fournit

  • Image LCP : passez 'is_lcp' => true dans les réglages de get_the_image() pour l’image principale au-dessus de la ligne de flottaison (hero, couverture). Cela retire loading="lazy" et ajoute fetchpriority="high". Définissez decoding dans $attributes uniquement si une mesure le justifie (ex. WebPageTest). Une seule image par page. Par défaut is_lcp => false (opt-in).
the_image( $image_id, [ 'alt' => '' ], [ 'size' => 'hero', 'is_lcp' => true ] );

  • ARI (Auto Responsive Images) : sur les projets avec ARI, ne pas activer is_lcp sur les images déjà gérées par ARI (taille / data-location au bon format). ARI pilote la priorité et le lazy-load ; is_lcp sur la même image est redondant ou incompatible. Réserver is_lcp aux projets sans ARI, ou valider manuellement (page hero avec ARI, sans is_lcp).

  • Images décoratives (alt="") — même objectif, deux helpers selon la source :

    • Médiathèque (the_image / get_the_image) : passez 'alt' => '' explicitement si l’image est décorative. Sinon WordPress reprend l’alt saisi dans le BO. Omettre la clé alt n’est pas équivalent à alt="".
    • Fichiers buildés dans dist/ (the_theme_static_image / get_theme_static_image_markup) : décoratif par défaut (alt="" si vous ne passez pas alt). Indiquez un texte d’alt si l’image porte du sens (ex. logo + nom du site). Ne pas utiliser the_image pour ces fichiers (pas d’ID attachment).

  • Images statiques du thème (placeholders, illustrations dans dist/) : le helper statique ajoute aussi width et height via dist/assets.json (imageDimensions, généré au build) pour limiter le CLS, sans lecture disque répétée lorsque le manifeste est présent. Hors manifeste : une lecture par chemin et par requête.

// Média (décoratif)
the_image( $image_id, [ 'alt' => '', 'class' => 'card__thumb' ], [ 'size' => 'card' ] );

// Asset dist/ (décoratif par défaut)
the_theme_static_image( 'dist/images/placeholder.svg', [ 'class' => 'card__image', 'loading' => 'lazy' ] );

// Asset dist/ (alt porteur de sens)
the_theme_static_image( 'dist/images/logo.svg', [ 'alt' => get_bloginfo( 'name' ), 'class' => 'header__logo' ] );
  • Preload des polices : opt-in, uniquement pour les polices rendues au premier affichage. Indiquez le chemin après build (ex. polices Fontsource ou custom copiées dans dist/fonts/, en .woff2).
add_filter( 'bea_theme_framework_preload_fonts', fn() => [ 'dist/fonts/my-font-regular.woff2' ] );
  • JS : Animation s’appuie sur IntersectionObserver (pas de boucle au scroll). Utilisez deferInitialization() depuis src/js/utils pour exécuter du code non critique lorsque le navigateur est inactif (INP).

Ce que chaque projet doit encore configurer

Cela dépend de l’hébergement, des extensions et du contenu ; ce n’est donc pas inclus dans le thème :

  • Cache de page et réglages WP Rocket (suppression du CSS inutilisé, différer / retarder le JS et leurs exclusions, exclusions du lazyload pour l’image LCP, preconnect limités aux tiers chargés tôt).
  • robots.txt (endpoints techniques et AJAX) et en-têtes Cache-Control pour les assets statiques.
  • Réglages du plugin SEO : URLs canoniques sur pagination personnalisée, doublons de données structurées.
  • Polices : sous-ensemble des fichiers aux graisses et glyphes réellement utilisés, suppression des fichiers inutiles (italiques, graisses supplémentaires).
  • Intégrations tierces (vidéos, formulaires, webinars) : chargement à l’interaction ou à l’entrée dans le viewport.
  • Assets des extensions : retirer les scripts et styles front (dequeue) sur les pages qui ne les utilisent pas.

Éditeur WordPress (Gutenberg)

Personnaliser les blocs

Le filtre bff_editor_custom_settings permet de personnaliser les styles et variations de blocs. Par exemple :

add_filter( 'bff_editor_custom_settings', 'customize_editor_settings', 10, 1 );
function customize_editor_settings( $settings ) {
	// Désactiver tous les styles du bloc Séparateur
	$settings[ 'disableAllBlocksStyles' ] = [ 'core/separator' ];

	// Désactiver le style outline du bloc Bouton
	$settings[ 'disabledBlocksStyles' ]   = [ 'core/button' => [ 'outline' ] ];

	// Autoriser uniquement la variation YouTube du bloc Intégration
	$settings[ 'allowedBlocksVariations' ] = [ 'core/embed' => [ 'youtube' ] ];

	return $settings;
}