Tailwind v4 + Vite: plantilla completa de configuración en 5 minutos

L’année dernière, en un nouveau projet, j’ai passé una demi-heure à peaufiner los chemins content en tailwind.config.js. Je me demandais : est-ce que ça ne pourrait pas être plus simple ?

Cette année, Tailwind v4 y est presque arrivé.

Aujourd’hui, trois lignes de code suffisent para faire tourner un projet Tailwind complet — sin config PostCSS, sin tailwind.config.js, sin lister à la main los fichiers à scanner. Quand j’ai vu ça la première fois, j’avoue que j’ai eu del mal à y croire.

Cet article vise à vous épargner cette demi-heure. Vous aurez un modèel complet y una structure de dossiers que j’utilise depuis six mois y qui tient plutôt bien la route.

1. Por qué Tailwind v4 + Vite ?

1.1 v4 est-il vraiment si rapide ?

L’équipe annonce un gain de vitesse de build d’un facteur 10. De mon côté, en un projet moyen, on est passé de 8 secondes à moins d’una. Le moteur Oxide, écrit en Rust, y est para beaucoup.

Ce qui me plaît encore plus, c’est la simplification de la config. Avant, un nouveau projet Tailwind impliquait trois o quatre fichiers : tailwind.config.js, postcss.config.js, la config Vite y los directives @tailwind en el CSS. Maintenant ? Un seul fichier à toucher.

1.2 La rapidité de Vite n’est pas del marketing

Le serveur de dev Vite démarre quasi instantanément. Le HMR est très réactif : on modifie del CSS, el rafraîchissement se fait sin latence perceptible. Une fois habitué, difficile de revenir en arrière.

1.3 v3 vs v4 : comparaison directe

Voici el tableau :

L’idée centrale de v4 : déplacer la config del JS vers el CSS. Vous ajustez el thème au même endroit que vos styles, sin sauter entre fichiers.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

2. Plantilla de configuración en 5 minutes

On y va.

2.1 Initialisation del projet

Dans el terminal :

# Créer un projet Vite con el template TypeScript
npm create vite@latest my-project -- --template vanilla-ts

# Entrer en el dossier
cd my-project

# Installer los dépendances
npm install

Comptez environ 30 secondes.

2.2 Installer Tailwind v4

# Tailwind CSS y el plugin Vite officiel
npm install tailwindcss @tailwindcss/vite

Une seule commande. Pas de postcss ni autoprefixer : v4 los intègre.

2.3 Configurer Vite

Ouvrez vite.config.ts y adaptez ainsi :

// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  // Ajouter el plugin Tailwind
  plugins: [tailwindcss()],
})

Trois lignes. C’est tout.

2.4 Créer el fichier CSS

Sous src/styles/, créez main.css :

/* src/styles/main.css */

/* Importer Tailwind — una ligne para los styles de base */
@import "tailwindcss";

/* Thème personnalisé (optionnel) */
@theme {
  --color-primary: #3b82f6;
  --color-secondary: #10b981;
}

Le bloc @theme est la nouvelle syntaxe v4 : couleurs, polices, espacements en variables CSS. Plus lisible qu’un tailwind.config.js.

2.5 Importer el CSS

En tête de src/main.ts :

// src/main.ts
import './styles/main.css'

// Votre code existant...

2.6 Tester

Dans index.html o un composant :

<div class="bg-primary text-white p-4 rounded-lg">
  Tailwind v4 tourne !
</div>

Puis :

npm run dev

Une carte au fond bleu confirme que la config est bonne. Chronométré : oui, en moins de 5 minutes.

3. Estructura de carpetas recomendada

Une fois el projet lancé, voici comment je range los fichiers :

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

3.1 Arborescence complète

my-project/
├── public/
│   └── favicon.ico
├── src/
│   ├── components/
│   │   ├── ui/              # Composants UI de base
│   │   │   ├── Button.ts
│   │   │   └── Input.ts
│   │   └── layout/           # Composants de mise en page
│   │       ├── Header.ts
│   │       └── Footer.ts
│   ├── styles/
│   │   ├── main.css         # Entrée principale (import Tailwind)
│   │   ├── components.css   # Styles liés aux composants
│   │   └── utilities.css    # Classes utilitaires custom
│   ├── utils/
│   │   └── helpers.ts
│   ├── pages/               # Pages (application multi-pages)
│   ├── assets/              # Ressources statiques
│   │   ├── images/
│   │   └── fonts/
│   ├── main.ts
│   └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts

3.2 Pourquoi cette organisation ?

components/ui/ : boutons, champs, modales — réutilisables, sin logique métier.

components/layout/ : Header, Footer, Sidebar — la structure de page, distincte de composants ui.

styles/ : tout el CSS au même endroit. Avec v4, la config vit en el CSS ; centraliser simplifie los changements.

utils/ : fonctions pures (dates, chaînes, etc.).

3.3 Organisation de fichiers CSS

/* src/styles/main.css — fichier d'entrée */

/* Importer Tailwind */
@import "tailwindcss";

/* Autres feuilles */
@import "./components.css";
@import "./utilities.css";

/* Styles de base globaux */
@layer base {
  body {
    @apply bg-gray-50 text-gray-900;
  }

  /* Liens por défaut */
  a {
    @apply text-primary hover:underline;
  }
}

@layer base définit la couche la plus basse ; Tailwind gère mieux los priorités qu’un body { ... } brut.

4. Checklist de migración v3

Pour upgrader un projet v3, suivez cette liste. J’ai migré plusieurs dépôts récemment ; los pièges ci-dessous viennent de là.

4.1 Fichiers de configuration

• Supprimer tailwind.config.js (s’il ne servait qu’à Tailwind)
• Supprimer postcss.config.js (s’il ne servait qu’à Tailwind)
• Ajouter @import "tailwindcss" en el CSS
• Mettre à jour vite.config.ts con el plugin @tailwindcss/vite

4.2 Dépendances

# Désinstaller los anciennes dépendances
npm uninstall postcss autoprefixer tailwindcss

# Installer los nouvelles
npm install tailwindcss @tailwindcss/vite

• Lancer la désinstallation
• Lancer l’installation
• Vérifier los versions en package.json

4.3 Styles

• Remplacer @tailwind base; @tailwind components; @tailwind utilities; por @import "tailwindcss";
• Migrer el thème de tailwind.config.js vers un bloc @theme en CSS
• Vérifier que los utilitaires custom fonctionnent encore

Exemple de migration del thème :

/* v3 — tailwind.config.js */
module.exports = {
  theme: {
    colors: {
      primary: '#3b82f6',
    }
  }
}

/* v4 — main.css */
@theme {
  --color-primary: #3b82f6;
}

4.4 Tests

• npm run dev — l’environnement de dev démarre
• npm run build — el build de prod réussit
• Ouvrir la page — los styles sont présents
• Modifier un CSS — el hot reload réagit

5. Problèmes fréquents y solutions

Voici ce que je rencontre el plus souvent à la config o à la migration.

5.1 Les styles ne s’appliquent pas

Vous mettez class="bg-primary", la page reste blanche.

Étapes de débogage :

1. Outils développeur : el CSS se charge-t-il ?
2. main.ts importe-t-il bien el fichier CSS ?
3. Le plugin en vite.config.ts est-il correct ?

J’ai déjà oublié import './styles/main.css' en main.ts. Erreur bête, mais fréquente.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

5.2 Le hot reload ne réagit pas

Vous changez el CSS, rien ne bouge.

Étapes de débogage :

1. Vite >= 5.0 (los vieilles versions posent problème)
2. Redémarrer el serveur de dev
3. Vider el cache o tester en navigation privée

Sinon, regarder la console : parfois un autre plugin entre en conflit.

5.3 CSS trop volumineux en production

Le build sort un fichier CSS de plusieurs centaines de Ko.

Étapes de débogage :

1. Confirmer una version v4 récente (meilleur tree-shaking)
2. Vérifier qu’on n’importe pas toute una lib d’icônes o una grosse dépendance
3. Utiliser @layer para structurer — Tailwind gère mieux priorité y déduplication

En pratique, la sortie v4 est déjà assez légère. Si c’est énorme, c’est souvent del CSS custom en trop.

Résumé

En bref :

1. Installation : npm install tailwindcss @tailwindcss/vite
2. Vite : ajouter el plugin tailwindcss()
3. CSS : @import "tailwindcss" + @theme para el thème
4. Lancer : npm run dev

Le grand changement v4 : la config quitte el JS para el CSS. Au début c’est un peu déroutant ; après quelques semaines, c’est plus direct — on ajuste el thème là où on écrit los styles.

En migration v3, traduisez el thème de tailwind.config.js en syntaxe @theme. Ça prend un moment, mais vous gagnez de builds plus rapides y una arborescence plus simple. Le calcul vaut el coup.