Tailwind CSS 4 setup e differenze dalla v3 — guida pratica • Meteora Web Agency

Hai appena letto di Tailwind 4 e ti chiedi cosa sia cambiato rispetto alla versione 3. Probabilmente hai visto post che parlano di novità ma non di come passare all'azione. Noi, di Meteora Web, abbiamo già aggiornato diversi progetti da v3 a v4 e vogliamo darti il nostro punto di vista – tecnico e operativo. Partiamo dal problema concreto: la documentazione ufficiale è ancora in evoluzione e molti tutorial su YouTube si basano su beta. Se non vuoi perdere tempo con configurazioni che tra un mese saranno obsolete, questa guida è per te.

Cos'è cambiato davvero in Tailwind 4

Tailwind CSS 4 non è un semplice aggiornamento di funzionalità. È un cambio di paradigma nel modo in cui il framework viene eseguito e configurato. Il vecchio sistema basato su PostCSS e un file tailwind.config.js pesante è stato sostituito da un engine nativo in Rust (Lightning CSS) che accelera la build e semplifica la personalizzazione. Per noi, che abbiamo visto clienti aspettare secondi per rigenerare il CSS in sviluppo, questo significa un risparmio di tempo reale – e il tempo, nel nostro lavoro, si traduce in fatturato.

Nuovo motore Lightning CSS

Tailwind 4 integra Lightning CSS al posto di PostCSS. Il risultato? Build 10x più veloci, supporto nativo a nesting CSS, import di file CSS moderni e minification automatica. Non devi più installare autoprefixer, postcss-import o cssnano: tutto è già incluso. La velocità non è un lusso — è la differenza tra potere iterare rapidamente su un layout o perdere la concentrazione mentre aspetti la compilazione.

Configurazione senza config file

La novità più dirompente: niente più tailwind.config.js obbligatorio. La configurazione avviene direttamente nel CSS tramite la direttiva @theme. Vuoi personalizzare il colore primario? Scrivi:

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #8b5cf6;
}

Questa sintassi elimina la duplicazione tra file JS e CSS, riduce gli errori e rende il tema portabile. Per noi, che gestiamo progetti con più clienti, significa poter condividere pezzi di tema tra siti diversi senza incartarsi su oggetti JSON.

Sintassi delle utility

Le utility class sono rimaste identiche – flex, p-4, text-lg – ma sono state riscritte per sfruttare le custom property CSS anziché i valori hard-coded. Questo permette di sovrascrivere i valori a runtime via JavaScript o media query, cosa che con v3 era possibile solo con trick CSS avanzati.

Setup di un progetto con Tailwind 4

Vediamo i passi concreti per iniziare oggi. Partiamo da un progetto vuoto. Se hai un progetto esistente con v3, salta alla sezione differenze più avanti.

Installazione con npm

Apri il terminale nella cartella del tuo progetto ed esegui:

npm install tailwindcss @tailwindcss/cli

Attenzione: in v4 il package CLI è separato. Se usi Vite, Next.js o Laravel, ci sono plugin dedicati. Per un progetto semplice, il CLI standalone è la via più rapida.

Il file CSS principale

Crea un file src/input.css con questo contenuto:

@import "tailwindcss";

@theme {
  --font-sans: 'Inter', sans-serif;
  --color-brand: #2563eb;
}

Nota: non serve più @tailwind base; @tailwind components; @tailwind utilities; – il singolo @import basta.

Build e watch

Ora lancia il comando di build:

npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch

Il flag --watch rigenera il CSS ad ogni modifica. Se apri il file dist/output.css vedrai già il risultato. Fatto. In meno di 5 minuti hai un setup funzionante.

Differenze pratiche tra v3 e v4

Ora entriamo nel dettaglio di cosa cambia quando si scrive codice o si personalizza un tema.

Colori e personalizzazione del tema

In v3 dovevi scrivere nel tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#2563eb',
      }
    }
  }
}

In v4 fai tutto nel CSS:

@import "tailwindcss";

@theme {
  --color-brand: #2563eb;
}

Poi nel tuo HTML usi bg-brand o text-brand esattamente come prima. La differenza? Il tema è ora un insieme di variabili CSS, quindi puoi anche modificarlo via JavaScript per temi dinamici (dark mode, personalizzazione utente).

Varianti (hover, focus, responsive)

Le varianti sono rimaste uguali – hover:, focus:, md:, dark: – ma ora puoi creare varianti personalizzate direttamente nel CSS senza plugin esterni. Esempio: vuoi un comportamento speciale quando l'utente ha il mouse? Scrivi:

@custom-variant pointer (&:hover) {
  /* nessuna azione extra necessaria */
}

Poi usi pointer:bg-red-500 nelle tue classi. Flessibilità senza Plugin: meno dipendenze, più controllo.

Plugin e compatibilità

La maggior parte dei plugin per v3 (typography, forms, aspect-ratio) sono già stati portati a v4. Tuttavia, se usi plugin molto specifici o non mantenuti, verifica la compatibilità. Noi, di Meteora Web, abbiamo notato che plugin come tailwindcss-forms funzionano già in v4, mentre alcuni plugin di terze parti per animazioni richiedono un aggiornamento. Consiglio: prima di migrare un progetto in produzione, fai un test su un ramo separato.

Errori comuni e come evitarli

Abbiamo visto sviluppatori incappare in questi errori durante la migrazione:

Import duplicati: se lasci il vecchio @tailwind base nel CSS, ottieni errori. Sostituisci tutto con @import "tailwindcss";.
Variabili custom non trovate: in v4 i valori del tema sono custom property CSS con prefisso --. Se hai usato theme('colors.brand') nel tuo JS, ora devi leggere getComputedStyle(element).getPropertyValue('--color-brand').
Dark mode class: in v4 la dark mode via classe (class="dark") è abilitata per default. Non devi più configurarla. Se il tuo progetto usava darkMode: 'class', puoi rimuoverlo.

Vale la pena migrare ora?

Se il tuo progetto è nuovo: parti direttamente con v4, non hai nulla da perdere e guadagni velocità e semplicità. Se hai un progetto esistente in v3: valutalo. La migrazione è meccanica per la maggior parte dei casi, ma richiede test. Noi abbiamo migrato un e-commerce con 30 pagine in circa 4 ore, risolvendo due piccole incompatibilità con plugin di animazione. Il ritorno? Build più veloci e un codice CSS più pulito – la manutenzione futura costa meno.

In sintesi — cosa fare adesso

Scarica l'ultima versione di Node.js (almeno 18.0.0) per supportare le funzionalità moderne.
Crea un nuovo progetto di test con il comando npm init -y e installa tailwindcss + CLI.
Segui i tre passaggi del setup sopra: input.css, build, e prova a scrivere una utility.
Se arrivi da v3, confronta il tuo tailwind.config.js con le direttive @theme e migra una pagina alla volta.
Leggi la documentazione ufficiale su Upgrade Guide v4 per un check completo.

Noi, di Meteora Web, lo usiamo già in produzione. Se hai dubbi, contattaci. La tecnologia cambia, ma il nostro approccio resta: misuriamo ogni strumento in termini di tempo risparmiato al cliente e qualità del risultato. Tailwind 4 è uno di quegli strumenti che danno un vantaggio concreto. Non lasciartelo scappare.