Le guide de configuration définitif que vous garderez précieusement pour tous vos projets React.

🎯 Pourquoi ce guide ?

Vous connaissez cette situation : nouveau projet React, et c’est reparti pour chercher :

• Les bonnes versions des dépendances
• La configuration optimale
• Les fichiers à créer
• Les commandes à exécuter

Ce guide résout définitivement ces problèmes en proposant un setup reproductible et documenté.

📊 Versions garanties et testées

Cette configuration utilise des versions spécifiques validées :

{
    "dependencies": {
        "react": "18.2.0",
        "react-dom": "18.2.0",
        "react-router-dom": "^6.22.3",
        "prop-types": "latest"
    },
    "devDependencies": {
        "vite": "6.1.1",
        "tailwindcss": "3.4.1",
        "postcss": "8.4.35",
        "autoprefixer": "10.4.17",
        "jsdoc": "latest"
    }
}

🛠️ Installation pas à pas

1️⃣ Création du projet

# Création du projet avec Vite
npm create vite@6.1.1 mon-projet -- --template react

# Navigation dans le dossier
cd mon-projet

# Installation de React 18
npm install react@18.2.0 react-dom@18.2.0
npm install react-router-dom@6.22.3

# Installation des dépendances de développement
npm install -D tailwindcss@3.4.1 postcss@8.4.35 autoprefixer@10.4.17

# Installation des outils de documentation et validation
npm install -D jsdoc
npm install prop-types

# Initialisation de Tailwind
npx tailwindcss init -p

2️⃣ Configuration des fichiers

📝 Tailwind CSS

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
export default {
    content: ["./index.html", "./src/**/*.{js,jsx}"],
    theme: {
        extend: {
            // Vous pourrez étendre le thème ici
            colors: {
                brand: "#1a73e8",
            },
        },
    },
    plugins: [],
};

⚙️ Vite

// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
    plugins: [react()],
    base: "./", // Crucial pour le déploiement
    build: {
        assetsDir: "assets",
        rollupOptions: {
            output: {
                assetFileNames: "assets/[name].[ext]",
            },
        },
    },
});

📚 JSDoc

// jsdoc.json
{
  "source": {
    "include": ["./src"],
    "includePattern": ".+\\.jsx?$"
  },
  "opts": {
    "destination": "./docs",
    "recurse": true,
    "readme": "./README.md"
  },
  "plugins": ["plugins/markdown"],
  "templates": {
    "cleverLinks": true,
    "monospaceLinks": true
  },
  "markdown": {
    "parser": "gfm",
    "hardwrap": true
  }
}

3️⃣ Configuration des styles

/* src/index.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Vos styles personnalisés peuvent être ajoutés ici */
@layer components {
    .btn-primary {
        @apply px-4 py-2 bg-brand text-white rounded hover:bg-opacity-90;
    }
}

4️⃣ Scripts npm

// package.json
{
    "scripts": {
        "dev": "vite", // Développement local
        "build": "vite build", // Build de production
        "preview": "vite preview", // Prévisualisation du build
        "docs": "jsdoc -c jsdoc.json", // Génération de la documentation
        "clean": "rm -rf dist docs" // Nettoyage des builds
    }
}

📖 Documentation avec JSDoc

Exemple de composant documenté

// src/components/Button.jsx
import PropTypes from "prop-types";

/**
 * Bouton réutilisable avec style Tailwind
 * @component
 * @param {Object} props - Propriétés du composant
 * @param {string} props.label - Texte affiché dans le bouton
 * @param {('primary'|'secondary')} [props.variant='primary'] - Style visuel du bouton
 * @param {Function} [props.onClick] - Fonction appelée au clic
 * @param {boolean} [props.disabled=false] - État désactivé du bouton
 *
 * @example
 * // Bouton primaire
 *  console.log('Cliqué!')} />
 *
 * @example
 * // Bouton secondaire désactivé
 *
 *
 * @returns {JSX.Element} Composant Button stylisé
 */
function Button({ label, variant = "primary", onClick, disabled = false }) {
    const baseStyles = "px-4 py-2 rounded transition-colors duration-200";
    const variantStyles = {
        primary: "bg-brand text-white hover:bg-opacity-90",
        secondary: "bg-gray-200 text-gray-800 hover:bg-gray-300",
    };

    return { label };
}

Button.propTypes = {
    label: PropTypes.string.isRequired,
    variant: PropTypes.oneOf(["primary", "secondary"]),
    onClick: PropTypes.func,
    disabled: PropTypes.bool,
};

export default Button;

🔍 Utilisation de la documentation

Génération de la documentation

# Générer la documentation
npm run docs

La documentation sera générée dans le dossier ./docs. Vous pouvez l’ouvrir dans votre navigateur :

# Sur macOS
open docs/index.html

# Sur Linux
xdg-open docs/index.html

# Sur Windows
start docs/index.html

🧪 Validation de l’installation

1. Démarrez le serveur de développement :

npm run dev

2. Créez un composant de test dans src/App.jsx :

import Button from './components/Button';

function App() {
  return (
    <div className="p-8 space-y-4">
      <h1 className="text-3xl font-bold text-brand">
        Mon Application React
      </h1>

      <div className="space-x-4">
        <Button 
          label="Bouton Principal" 
          onClick={() => alert('Cliqué!')}
        />

        <Button 
          label="Bouton Secondaire" 
          variant="secondary"
        />

        <Button 
          label="Bouton Désactivé" 
          disabled
        />
      </div>
    </div>
  );
}

export default App;

📝 Structure du projet

mon-projet/
├── docs/                 # Documentation générée
├── src/
│   ├── components/      # Composants React
│   ├── App.jsx         # Composant principal
│   └── index.css       # Styles Tailwind
├── index.html
├── jsdoc.json          # Configuration JSDoc
├── package.json        # Dépendances et scripts
├── tailwind.config.js  # Configuration Tailwind
└── vite.config.js      # Configuration Vite

🚀 Bonnes pratiques

1. Organisation des composants

   • Un composant par fichier
   • Documentation JSDoc complète
   • Validation des props avec PropTypes

2. Styles Tailwind

   • Utiliser @layer pour les styles personnalisés
   • Privilégier les classes utilitaires
   • Créer des composants pour les styles répétitifs

3. Documentation

   • Documenter tous les composants réutilisables
   • Inclure des exemples d’utilisation
   • Générer la documentation avant chaque commit important

⚠️ Points d’attention

1. Versions

   • Garder les versions spécifiques dans package.json
   • Vérifier les mises à jour de sécurité
   • Tester après chaque mise à jour majeure

2. Performance

   • Tailwind purgera automatiquement les classes non utilisées en production
   • Vite optimisera automatiquement le bundle
   • La documentation n’est pas incluse dans le build de production

🔄 Maintenance

Cette configuration restera valide jusqu’à :

• Une mise à jour majeure de React (> 18.x)
• Une mise à jour majeure de Vite (> 6.x)
• Une mise à jour majeure de Tailwind CSS (> 3.x)

📚 Ressources utiles

• Documentation React
• Documentation Vite
• Documentation Tailwind
• Guide JSDoc

---

Dernière mise à jour : 03 mars 2025

Note : Ce guide est maintenu et testé régulièrement. Si vous rencontrez des problèmes, vérifiez les versions de vos dépendances.