Tailwind v4 + Vite : modèle de configuration en 5 minutes et structure de dossiers

L’année dernière, sur un nouveau projet, j’ai passé une demi-heure à peaufiner les chemins content dans 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 pour faire tourner un projet Tailwind complet — sans config PostCSS, sans tailwind.config.js, sans lister à la main les fichiers à scanner. Quand j’ai vu ça la première fois, j’avoue que j’ai eu du mal à y croire.

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

1. Pourquoi 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é, sur un projet moyen, on est passé de 8 secondes à moins d’une. Le moteur Oxide, écrit en Rust, y est pour beaucoup.

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

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

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

1.3 v3 vs v4 : comparaison directe

Voici le tableau :

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

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

2. Modèle de configuration en 5 minutes

On y va.

2.1 Initialisation du projet

Dans le terminal :

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

# Entrer dans le dossier
cd my-project

# Installer les dépendances
npm install

Comptez environ 30 secondes.

2.2 Installer Tailwind v4

# Tailwind CSS et le plugin Vite officiel
npm install tailwindcss @tailwindcss/vite

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

2.3 Configurer Vite

Ouvrez vite.config.ts et adaptez ainsi :

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

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

Trois lignes. C’est tout.

2.4 Créer le fichier CSS

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

/* src/styles/main.css */

/* Importer Tailwind — une ligne pour les 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 le CSS

En tête de src/main.ts :

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

// Votre code existant...

2.6 Tester

Dans index.html ou 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. Structure de dossiers recommandée

Une fois le projet lancé, voici comment je range les fichiers :

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

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, sans logique métier.

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

styles/ : tout le CSS au même endroit. Avec v4, la config vit dans le CSS ; centraliser simplifie les changements.

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

3.3 Organisation des 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 par défaut */
  a {
    @apply text-primary hover:underline;
  }
}

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

4. Checklist de migration v3

Pour upgrader un projet v3, suivez cette liste. J’ai migré plusieurs dépôts récemment ; les 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" dans le CSS
• Mettre à jour vite.config.ts avec le plugin @tailwindcss/vite

4.2 Dépendances

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

# Installer les nouvelles
npm install tailwindcss @tailwindcss/vite

• Lancer la désinstallation
• Lancer l’installation
• Vérifier les versions dans package.json

4.3 Styles

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

Exemple de migration du 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 — le build de prod réussit
• Ouvrir la page — les styles sont présents
• Modifier un CSS — le hot reload réagit

5. Problèmes fréquents et solutions

Voici ce que je rencontre le plus souvent à la config ou à 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 : le CSS se charge-t-il ?
2. main.ts importe-t-il bien le fichier CSS ?
3. Le plugin dans vite.config.ts est-il correct ?

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

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

5.2 Le hot reload ne réagit pas

Vous changez le CSS, rien ne bouge.

Étapes de débogage :

1. Vite >= 5.0 (les vieilles versions posent problème)
2. Redémarrer le serveur de dev
3. Vider le cache ou 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 une version v4 récente (meilleur tree-shaking)
2. Vérifier qu’on n’importe pas toute une lib d’icônes ou une grosse dépendance
3. Utiliser @layer pour structurer — Tailwind gère mieux priorité et déduplication

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

Résumé

En bref :

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

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

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