Scalare Tailwind nei monorepo

Un monorepo è un singolo repository che contiene più pacchetti o applicazioni, gestito con strumenti come Turborepo, Nx o gli workspace di pnpm. Quando più applicazioni di un monorepo usano Tailwind, è importante condividere la configurazione. Senza una configurazione condivisa, ogni applicazione duplica i token dei colori, i font e le configurazioni dei plugin, divergendosi gradualmente fino a rendere incoerente l'interfaccia tra i prodotti.

Estragga la configurazione di Tailwind in un pacchetto dedicato, generalmente denominato @repo/tailwind-config o @acme/tailwind-config. Questo pacchetto esporta un oggetto di configurazione di base che ogni applicazione utilizzatrice importa ed estende. Il pacchetto condiviso risiede in packages/tailwind-config/ e dispone di un proprio package.json che lo contrassegna come dipendenza interna.

Ogni applicazione importa la configurazione condivisa usando require e la combina o fonde con le sovrascritture specifiche dell'applicazione. Il file tailwind.config.js dell'applicazione aggiunge i propri percorsi content (poiché i percorsi dei contenuti sono sempre specifici dell'applicazione) e qualsiasi estensione propria di quell'applicazione. La configurazione condivisa gestisce tutti i token comuni del tema e i plugin.

Il sistema di preset di Tailwind è il meccanismo ufficialmente supportato per condividere le configurazioni. Un preset è un oggetto passato all'array presets nella configurazione dell'applicazione utilizzatrice. A differenza della combinazione diretta dell'oggetto di configurazione, i preset vengono fusi in modo intelligente da Tailwind: le estensioni del tema vengono unite in profondità, i plugin vengono concatenati e gli array content vengono combinati senza doverli unire manualmente.

Un problema critico nei monorepo: se dispone di una libreria di componenti condivisa packages/ui che esporta componenti con classi Tailwind, l'applicazione utilizzatrice deve includere i file di quel pacchetto nel proprio array content. In caso contrario, il motore JIT non analizza i componenti condivisi e le classi utilizzate al loro interno vengono eliminate dalla build di produzione.

In un monorepo con workspace pnpm o npm, aggiunga il pacchetto di configurazione condiviso come dipendenza di sviluppo usando il protocollo workspace. In questo modo viene creato un collegamento simbolico al pacchetto locale senza pubblicarlo su npm. Il package.json dell'applicazione utilizzatrice elenca @acme/tailwind-config: workspace:* e gli strumenti di build lo risolvono automaticamente nel pacchetto locale.

In un monorepo Turborepo, configuri la pipeline di turbo.json per memorizzare nella cache gli output della build di Tailwind. Poiché la configurazione condivisa è una dipendenza della build di ogni applicazione, le modifiche a packages/tailwind-config invalidano correttamente la cache della build per tutte le applicazioni utilizzatrici. In questo modo si evita di distribuire CSS obsoleto quando il design system viene aggiornato.

I percorsi dei contenuti sono l'unica configurazione che non può essere condivisa: devono essere locali a ogni applicazione. Applicazioni diverse hanno strutture di directory diverse. Eviti la tentazione di inserire i percorsi dei contenuti nella configurazione condivisa: così facendo, potrebbe non individuare alcuni file o analizzarne troppi. La configurazione condivisa dovrebbe esportare solo tema, plugin e preset. I contenuti devono essere sempre definiti localmente nella configurazione di ogni applicazione utilizzatrice.

Anche se il pacchetto di configurazione condiviso è privato (non viene mai pubblicato su npm), lo gestisca seguendo una disciplina di versionamento. Incrementi la versione nel package.json a ogni modifica incompatibile, ad esempio la rimozione di un colore, la ridenominazione di un token o la rimozione di un plugin. Gli utilizzatori del preset potranno così fissare una versione e aggiornarla consapevolmente, invece di permettere che modifiche incompatibili si propaghino silenziosamente a tutte le applicazioni contemporaneamente.

In questa lezione ha imparato a: creare un pacchetto di configurazione Tailwind condiviso usando il sistema ufficiale dei preset per un merge profondo intelligente, includere i file del pacchetto UI condiviso nei percorsi dei contenuti per impedire l'eliminazione delle classi e trattare le modifiche alla configurazione come modifiche incompatibili tra app, con versionamento e test di regressione visiva. Nel prossimo capitolo progetteremo un sistema di design Tailwind completo per il progetto finale.

Se usa Storybook nel pacchetto UI condiviso per documentare i componenti, configuri Storybook in modo che utilizzi lo stesso preset Tailwind condiviso. Aggiunga l'add-on Tailwind per Storybook (@storybook/addon-styling-webpack o l'equivalente per il framework) e gli faccia usare la configurazione condivisa. In questo modo, i componenti vengono visualizzati in Storybook con gli stessi token utilizzati nelle app.

In this lesson you learned: creating a shared Tailwind config package using the official preset system for intelligent deep-merging, including shared UI package files in content paths to prevent class purging, and treating config changes as cross-app breaking changes with versioning and visual regression tests. Next up we plan a complete Tailwind design system for the capstone project.