TypeScript pour vos blocs Gutenberg : configuration et typage des attributs

La question revient régulièrement de développeurs habitués à TypeScript sur d’autres projets React : est-ce viable de l’introduire sur un bloc Gutenberg sans passer des jours à configurer une chaîne de build maison ? La réponse tient en une bonne nouvelle et une réserve : la configuration de base ne demande presque rien, mais la couverture de types des paquets @wordpress/* reste inégale selon les paquets.

Configuration : presque rien à faire

@wordpress/scripts détecte automatiquement les fichiers .ts et .tsx et les compile sans configuration Webpack additionnelle, à condition d’installer TypeScript et les définitions de types nécessaires :

npm install --save-dev typescript @types/wordpress__blocks @types/wordpress__block-editor @types/wordpress__components

Un fichier tsconfig.json minimal suffit pour la vérification de types (à ne pas confondre avec la compilation, déjà gérée par wp-scripts) :

{
	"compilerOptions": {
		"target": "ES2020",
		"module": "ESNext",
		"jsx": "react-jsx",
		"strict": true,
		"moduleResolution": "node",
		"esModuleInterop": true,
		"skipLibCheck": true,
		"noEmit": true
	},
	"include": [ "src/**/*.ts", "src/**/*.tsx" ]
}

noEmit: true est volontaire : la compilation réelle reste à la charge de wp-scripts via Webpack, TypeScript ne sert ici qu’à la vérification de types, exécutée séparément avec tsc --noEmit.

Typer les attributs d’un bloc

interface BlockAttributes {
	titre: string;
	nombreColonnes: number;
	afficherPrix: boolean;
}

interface EditProps {
	attributes: BlockAttributes;
	setAttributes: ( attributes: Partial< BlockAttributes > ) => void;
}

export default function Edit( { attributes, setAttributes }: EditProps ) {
	return (
		<RangeControl
			label="Colonnes"
			value={ attributes.nombreColonnes }
			onChange={ ( nombreColonnes ) =>
				nombreColonnes !== undefined &&
				setAttributes( { nombreColonnes } )
			}
			min={ 1 }
			max={ 6 }
		/>
	);
}

Ce typage explicite attrape immédiatement une classe entière de bugs fréquents : passer une chaîne de caractères là où un nombre est attendu, oublier un attribut lors d’un appel à setAttributes, ou confondre le nom d’un attribut avec un autre proche dans un gros bloc à plusieurs dizaines de réglages.

Le piège : des types @wordpress/* incomplets

Certains paquets, comme @wordpress/block-editor ou @wordpress/components, bénéficient de définitions de types communautaires maintenues via @types/wordpress__*, mais leur couverture reste parfois en retard par rapport aux dernières fonctionnalités ajoutées au cœur de Gutenberg. Un composant récemment introduit peut ainsi ne pas être typé du tout, obligeant à un typage local temporaire :

// Pis-aller ponctuel, à ne pas généraliser à tout le projet
// @ts-expect-error — type manquant pour ce composant récent
import { ComposantTropRecent } from '@wordpress/block-editor';

Cette solution reste un pis-aller, pas une pratique à généraliser : mieux vaut isoler ce genre de contournement à un endroit clairement identifié du code, avec un commentaire expliquant pourquoi, plutôt que de désactiver strict pour tout le projet.

RichText et le typage de la valeur

Un attribut relié à un composant RichText pose une difficulté propre : la valeur manipulée n’est pas une simple chaîne de caractères mais un objet interne au paquet @wordpress/rich-text, ce qui demande d’importer le type correspondant plutôt que de le remplacer naïvement par string.

• Un attribut de type rich-text côté block.json correspond, côté TypeScript, à une chaîne HTML sérialisée, pas à l’objet interne du composant.
• Le typage strict des props de RichText lui-même reste l’un des points les moins bien couverts des définitions communautaires actuelles.

Sur un projet avec plusieurs blocs et plusieurs développeurs, le typage strict des attributs justifie largement le temps de configuration initiale, même avec les lacunes ponctuelles des types communautaires : la majorité des bugs qu’il évite se produiraient de toute façon en production, pas en développement.

Notre verdict

TypeScript s’intègre à une chaîne de build @wordpress/scripts avec un effort de configuration minime, et le typage des attributs reste le gain le plus net pour un bloc de complexité moyenne à élevée. Les lacunes ponctuelles des types communautaires restent gérables au cas par cas, sans remettre en cause l’intérêt global de l’approche.