Pièges et alternatives de @apply

Bien que @apply semble être un moyen pratique d’organiser les styles, son utilisation excessive entraîne plusieurs problèmes bien documentés. Ceux-ci comprennent la difficulté à comprendre quels utilitaires sont actifs, la perte d’une source unique de vérité pour les styles des composants et des surprises liées à la spécificité. Comprendre ces pièges vous aide à déterminer quand @apply est réellement le bon outil et quand une meilleure solution existe.

Le mauvais usage le plus courant de @apply consiste à l’utiliser pour recréer des classes CSS conventionnelles : donner à chaque élément une seule classe sémantique comme .header-title, puis la remplir d’utilitaires. C’est exactement le modèle dont Tailwind a été conçu pour s’éloigner. Vous cumulez les inconvénients des deux approches : des fichiers CSS verbeux ET un HTML qui exige de savoir quelles classes CSS existent. Le résultat est plus difficile à maintenir que l’une ou l’autre approche utilisée seule.

Lorsque vous masquez des classes utilitaires dans des règles @apply d’un fichier CSS, elles deviennent invisibles pour l’analyseur JIT, sauf si le fichier CSS figure dans votre tableau content. Plus important encore, les développeurs qui liront votre HTML ultérieurement ne pourront pas voir tous les styles d’un seul coup d’œil : ils devront ouvrir le fichier CSS, trouver la classe et développer mentalement le contenu de @apply. Cela réduit le caractère auto-documenté de l’approche utilitaire de Tailwind.

Lorsque vous utilisez @apply sans placer le résultat dans @layer components, le bloc CSS compilé se trouve à l’emplacement de votre feuille de styles où vous l’avez écrit. Cela peut provoquer des problèmes de spécificité inattendus, la classe de votre composant prenant le dessus sur les utilitaires intégrés, car elle apparaît plus loin dans le fichier. Utilisez toujours @layer components afin que la cascade des couches gère la spécificité de manière prévisible.

La syntaxe des valeurs arbitraires de Tailwind (notation entre crochets, comme w-[347px] ou bg-[#1a2b3c]) ne fonctionne pas dans @apply. Il s’agit d’une limitation fondamentale : les valeurs arbitraires sont résolues lorsque l’analyseur JIT les trouve dans les fichiers source, tandis que @apply intervient à une autre étape. Si votre composant nécessite des valeurs ponctuelles, vous devez utiliser des propriétés CSS classiques dans la règle plutôt que des utilitaires à valeurs arbitraires.

Dans React et les autres frameworks de composants, la meilleure alternative à @apply est une abstraction de composant. Un composant Button accepte une propriété variant et génère en interne les bonnes classes utilitaires. Les styles sont encapsulés, l’API est typée et les modifications sont répercutées partout où le composant est utilisé. C’est le modèle recommandé par l’équipe Tailwind pour les bases de code composées principalement de composants.

La bibliothèque clsx (ou son alternative classnames) permet de composer proprement des classes conditionnelles en JavaScript. Au lieu de concaténer des chaînes ou d’utiliser des littéraux de modèle, transmettez un objet ou un tableau à clsx : la bibliothèque se charge de les assembler selon les conditions. C’est la manière de référence de gérer les classes de variantes dans les composants React sans @apply.

Dans les projets HTML sans framework (par exemple les applications générées côté serveur avec les modèles Django, Laravel ou Go), l’équivalent d’un composant est un fragment de modèle ou un include. Extrayez le fragment HTML répété avec ses utilitaires dans un fragment, puis incluez-le partout où cela est nécessaire. Vous obtenez ainsi le même avantage en matière de duplication qu’avec @apply, tout en conservant les styles dans le HTML, là où ils doivent se trouver.

Après avoir compris les pièges, vous pouvez repérer les cas réels où @apply est l’outil approprié. Il s’agit notamment de la mise en forme d’un HTML que vous ne pouvez pas contrôler (Markdown généré, sortie d’un CMS, HTML d’une bibliothèque tierce), de l’harmonisation des éléments de formulaire du navigateur avec le plugin de formulaires et de l’ajout d’utilitaires Tailwind à des éléments SVG ou canvas externes. Dans ces cas, vous ne pouvez pas ajouter de classe à l’élément : @apply est donc la seule option.

L’équipe Tailwind CSS déconseille explicitement d’utiliser @apply pour organiser les styles simplement parce que cela « semble plus propre ». Sa documentation indique : « If you find yourself wanting to use @apply to DRY up your Tailwind CSS, you should probably be using a component. » Les abstractions de composants sont plus explicites, plus faciles à rechercher et plus faciles à maintenir à grande échelle. @apply doit être une solution de dernier recours, et non un premier réflexe.

Si vous disposez d’un projet existant qui utilise abondamment @apply, vous pouvez migrer progressivement vers des composants. Commencez par la classe de composant la plus utilisée (généralement les boutons ou les cartes), créez un composant adapté, puis remplacez les utilisations fichier par fichier. Chaque remplacement améliore la sécurité offerte par le typage, la proximité des styles et la lisibilité. La migration présente peu de risques, car le rendu visuel devrait être identique : vous ne changez que le mécanisme, pas la conception.

Dans cette leçon, vous avez appris que les pièges de @apply incluent la reproduction du CSS traditionnel, la dissimulation des styles pour les lecteurs du HTML et l’absence de prise en charge des valeurs arbitraires ; que les meilleures alternatives sont les composants JSX avec clsx pour React ou les fragments de modèles pour les applications générées côté serveur ; et que @apply doit être réservé au HTML que vous ne pouvez pas contrôler, comme le Markdown généré par un CMS. Nous allons maintenant étudier les utilitaires de transition et d’animation de Tailwind.