Problemi e alternative di @apply

Sebbene @apply sembri un modo pratico per organizzare gli stili, un uso eccessivo crea una serie di problemi ben documentati. Tra questi vi sono la difficoltà nel capire quali utility siano attive, la perdita di un'unica fonte di verità per gli stili dei componenti e sorprese legate alla specificità. Comprendere queste insidie aiuta a decidere quando @apply sia davvero lo strumento giusto e quando esista un'alternativa migliore.

L'uso improprio più comune di @apply consiste nell'utilizzarlo per ricreare le classi CSS convenzionali, facendo sì che ogni elemento abbia una singola classe semantica come .header-title e riempiendola poi di utility. È esattamente lo schema dal quale Tailwind è stato progettato per allontanarsi. Si finisce con gli svantaggi di entrambi gli approcci: file CSS prolissi e HTML che richiede di sapere quali classi CSS esistono. Il risultato è più difficile da mantenere rispetto a ciascuno dei due approcci considerato singolarmente.

Quando nasconde le classi utility all'interno delle regole @apply in un file CSS, diventano invisibili allo scanner JIT, a meno che il file CSS non sia incluso nell'array content. Ancora più importante, i futuri sviluppatori che leggono il codice HTML non possono vedere tutti gli stili a colpo d'occhio: devono aprire il file CSS, trovare la classe ed espandere mentalmente @apply. Questo riduce la natura autoesplicativa dell'approccio utility-first di Tailwind.

Quando usa @apply senza inserire il risultato in @layer components, il blocco CSS compilato viene collocato nella posizione del foglio di stile in cui lo ha scritto. Questo può causare problemi imprevisti di specificità, per cui la classe del componente prevale sulle utility inline perché compare più avanti nel file. Usi sempre @layer components per assicurarsi che la cascata dei livelli gestisca la specificità in modo prevedibile.

La sintassi dei valori arbitrari di Tailwind (la notazione tra parentesi quadre, come w-[347px] o bg-[#1a2b3c]) NON funziona all'interno di @apply. Si tratta di una limitazione fondamentale: i valori arbitrari vengono risolti dallo scanner JIT quando li trova nei file sorgente, mentre @apply opera in una fase diversa. Se il componente richiede valori specifici usati una sola volta, deve usare normali proprietà CSS all'interno della regola anziché utility con valori arbitrari.

In React e negli altri framework basati su componenti, la migliore alternativa a @apply è un'astrazione di componente. Un componente Button accetta una prop variant e restituisce internamente le utility corrette. Gli stili sono incapsulati, l'API è tipizzata e le modifiche si propagano ovunque venga usato il componente. Questo è il pattern consigliato dal team di Tailwind per i codebase composti principalmente da componenti.

La libreria clsx (o la sua alternativa classnames) rende ordinata la composizione condizionale delle classi in JavaScript. Invece di concatenare stringhe o usare template literal, passi un oggetto o un array a clsx, che gestisce l'unione condizionale. Questo è il modo standard per gestire le classi delle varianti nei componenti React senza @apply.

Nei progetti HTML che non usano framework (come le applicazioni con rendering lato server che usano i template di Django, Laravel o Go), l'equivalente di un componente è un partial di template o un include. Estragga il frammento HTML ripetuto, insieme alle relative utility, in un partial e lo includa dove serve. In questo modo ottiene lo stesso vantaggio in termini di riduzione delle duplicazioni offerto da @apply, mantenendo però gli stili nell'HTML, dove devono stare.

Dopo aver compreso i problemi, può individuare i casi reali in cui @apply è lo strumento corretto. Tra questi rientrano: lo stile di HTML che non può controllare (markdown renderizzato, output di un CMS, HTML di librerie di terze parti), la normalizzazione degli elementi dei moduli del browser insieme al plugin per i moduli e l'aggiunta di utility Tailwind a elementi SVG o canvas esterni. In questi casi non può aggiungere una classe all'elemento, quindi @apply è l'unica opzione.

Il team di Tailwind CSS sconsiglia esplicitamente di usare @apply per organizzare gli stili solo perché «sembra più ordinato». La documentazione afferma: «If you find yourself wanting to use @apply to DRY up your Tailwind CSS, you should probably be using a component.» Le astrazioni di componente sono più esplicite, più facili da cercare e più manutenibili su larga scala. @apply dovrebbe essere l'ultima risorsa, non la prima scelta.

Se ha un progetto esistente che fa ampio uso di @apply, può procedere gradualmente verso i componenti. Inizi dalla classe di componente usata più di frequente (di solito pulsanti o card), crei un componente adeguato e sostituisca gli utilizzi un file alla volta. Ogni sostituzione migliora la sicurezza dei tipi, la co-localizzazione degli stili e la leggibilità. La migrazione è a basso rischio, perché l'output visivo dovrebbe rimanere identico: cambia solo il meccanismo, non il design.

In questa lezione ha imparato che i problemi di @apply includono la ricreazione del CSS tradizionale, il nascondere gli stili a chi legge l'HTML e il mancato funzionamento con i valori arbitrari; le alternative migliori sono i componenti JSX con clsx per React o i partial di template per le applicazioni con rendering lato server; infine, @apply dovrebbe essere riservato all'HTML che non può controllare, come il markdown renderizzato da un CMS. Nella prossima lezione esploreremo le utility di Tailwind per transizioni e animazioni.