🚀 Vite React TypeScript Core Template

⚡ Quick Start

🎯 Méthode 1: NPM Create (Recommandé) ⚡

1# Nouvelle méthode officielle avec npm create
2npm create vite-rubaine-react-ts@latest mon-projet
3cd mon-projet
4npm install
5cp .env.example .env     # Configurer votre API_URL
6npm run dev              # Démarrer le serveur ⚡

🎯 Méthode 2: GitHub Template

1# Cliquez sur "Use this template" ↗️ en haut de cette page GitHub
2# puis clonez votre nouveau repo et lancez :
3npm install
4cp .env.example .env     # Configurer votre API_URL
5npm run dev              # Démarrer le serveur ⚡

🎯 Méthode 3: Clone Git

1git clone https://github.com/Rubaine/vite-react-typescript-template.git mon-projet
2cd mon-projet
3rm -rf .git && git init  # Initialiser votre nouveau repo
4npm install
5cp .env.example .env
6npm run dev

🎯 Méthode 4: Degit

1npx degit Rubaine/vite-react-typescript-template mon-projet
2cd mon-projet
3npm install
4cp .env.example .env
5npm run dev

✨ Votre app est prête ! → http://localhost:5173 avec authentification JWT fonctionnelle.

💡 Méthode recommandée : Utilisez npm create vite-rubaine-react-ts@latest pour la création la plus rapide !

💡 Astuce : Le template inclut une page d'accueil avec des explications détaillées et exemples d'usage

📋 Table des matières

• ✨ Fonctionnalités
• 🏗️ Structure du projet
• 🚀 Installation
• ⚙️ Configuration
• 🔧 Utilisation
• 📚 API Reference
• 💡 Exemples pratiques
• 🛠️ Scripts & Build
• 🤝 Contribution
• 📝 Changelog

✨ Fonctionnalités

🏗️ Structure du projet

📦 src/
├── 🎯 core/                    # Fonctionnalités réutilisables
│   ├── 🌐 api/                 # Client API et utilitaires fetch
│   │   └── fetch.tsx           # GET, POST, PUT, DELETE + withAuth()
│   ├── 🔐 auth/                # Système d'authentification
│   │   └── AuthContext.tsx     # Context React + hooks
│   └── ⚙️ config/              # Configuration globale
│       ├── global.tsx          # Config app (URLs, etc.)
│       ├── protectedRoute.tsx  # HOC route protégée
│       └── types.ts            # Types TypeScript
├── 🧩 components/              # Composants réutilisables
├── 📱 views/                   # Vues/Pages de l'application
│   └── Home/                   # Page d'accueil avec documentation
│       ├── Home.tsx            # Composant page d'accueil
│       └── Home.css            # Styles de la page
├── App.tsx                     # Composant principal + routing
└── main.tsx                    # Point d'entrée

💡 Note : Le dossier views/ contient vos pages principales. Organisez vos composants selon vos préférences !

💡 Le dossier core/ est le cœur du template - copiez-le dans vos nouveaux projets !

🚀 Installation

1# Nouvelle méthode officielle
2npm create vite-rubaine-react-ts@latest mon-projet
3cd mon-projet
4npm install

1git clone https://github.com/votre-username/votre-projet.git
2cd votre-projet
3npm install

1git clone https://github.com/Rubaine/vite-react-typescript-template.git mon-projet
2cd mon-projet
3rm -rf .git  # Supprimer l'historique git
4git init     # Initialiser votre propre repo
5npm install

1npx degit Rubaine/vite-react-typescript-template mon-projet
2cd mon-projet
3npm install

1# 1. Configuration environnement
2cp .env.example .env
3nano .env  # Éditer VITE_API_URL
4
5# 2. Personnalisation package.json
6nano package.json  # Changer name, description, author
7
8# 3. Initialiser Git (si clone direct)
9rm -rf .git
10git init
11git add .
12git commit -m "🎉 Initial commit from vite-react-core-template"
13
14# 4. Premier build de test
15npm run build
16npm run preview

⚙️ Configuration

1. Variables d'environnement

Créer un fichier .env à la racine :

1# URL de votre API backend
2VITE_API_URL=http://localhost:5000
3
4# Optionnel : autres variables
5VITE_APP_NAME=MonApp

2. Configuration de l'authentification

Personnaliser la configuration dans App.tsx :

1<AuthProvider
2  config={{
3    endpoints: {
4      verify: "/api/auth/me", // Endpoint de vérification
5      refresh: "/api/auth/refresh", // Endpoint de refresh token
6    },
7    storage: {
8      tokenKey: "access_token", // Clé localStorage pour le token
9      userKey: "current_user", // Clé localStorage pour l'utilisateur
10    },
11    autoVerify: false, // Désactiver la vérification auto
12  }}
13>
14  <App />
15</AuthProvider>

3. Configuration de l'API

Modifier src/core/config/global.tsx :

1export const Config = {
2  Urls: {
3    API: import.meta.env.VITE_API_URL || "http://localhost:3000/api",
4  },
5  App: {
6    Name: "Mon Application",
7    Version: "1.0.0",
8  },
9};

🔧 Utilisation

Authentification

1import { useAuth } from "./core/auth/AuthContext";
2
3function LoginForm() {
4  const { login, logout, isAuthenticated, user, loading } = useAuth();
5
6  // Vérifier l'état de chargement
7  if (loading) return <div>Chargement...</div>;
8
9  // Connecter un utilisateur
10  const handleLogin = async (credentials) => {
11    const response = await postFetch("/auth/login", credentials);
12    if (response.success) {
13      login(
14        response.data.token,
15        response.data.refreshToken,
16        response.data.user
17      );
18    }
19  };
20
21  // Interface conditionnelle
22  return isAuthenticated ? (
23    <div>
24      <h1>Bonjour {user?.name}!</h1>
25      <button onClick={logout}>Se déconnecter</button>
26    </div>
27  ) : (
28    <LoginForm onSubmit={handleLogin} />
29  );
30}

Organisation des vues

Le template utilise une organisation claire des vues dans le dossier src/views/ :

1// src/views/Home/Home.tsx - Page d'accueil avec documentation
2export default function Home() {
3  return (
4    <div className="container mt-4">
5      {/* Documentation intégrée du template */}
6      <h1>🚀 Template React + TypeScript + Vite</h1>
7      {/* Explications et exemples d'usage */}
8    </div>
9  );
10}
11
12// Créez vos nouvelles vues de la même manière :
13// src/views/Dashboard/Dashboard.tsx
14// src/views/Profile/Profile.tsx
15// etc.

💡 Conseil : La page Home actuelle contient toute la documentation du template. Remplacez-la par votre vraie page d'accueil une fois familiarisé avec le template.

Requêtes API

1import { getFetch, postFetch, withAuth } from "./core/api/fetch";
2import { useAuth } from "./core/auth/AuthContext";
3
4function UserProfile() {
5  const { token } = useAuth();
6  const [user, setUser] = useState(null);
7
8  // GET avec authentification
9  const fetchProfile = async () => {
10    const response = await getFetch<User>("/profile", withAuth(token));
11    if (response.success) {
12      setUser(response.data);
13    } else {
14      console.error(response.error);
15    }
16  };
17
18  // POST avec données
19  const updateProfile = async (data) => {
20    const response = await postFetch<User>("/profile", data, withAuth(token));
21    if (response.success) {
22      setUser(response.data);
23    }
24  };
25
26  // Upload de fichier
27  const uploadAvatar = async (file) => {
28    const formData = new FormData();
29    formData.append("avatar", file);
30
31    const response = await postFetch<User>(
32      "/profile/avatar",
33      formData,
34      withAuth(token)
35    );
36    // La détection FormData est automatique
37  };
38}

Routes protégées

1import { Routes, Route } from "react-router-dom";
2import ProtectedRoute from "./core/config/protectedRoute";
3import Home from "./views/Home/Home";
4
5function App() {
6  return (
7    <Routes>
8      {/* Routes publiques */}
9      <Route path="/" element={<Home />} />
10      <Route path="/login" element={<Login />} />
11      <Route path="/register" element={<Register />} />
12
13      {/* Routes protégées */}
14      <Route element={<ProtectedRoute />}>
15        <Route path="/dashboard" element={<Dashboard />} />
16        <Route path="/profile" element={<Profile />} />
17        <Route path="/settings" element={<Settings />} />
18      </Route>
19    </Routes>
20  );
21}

💡 Structure recommandée : Placez vos nouvelles pages dans src/views/ et vos composants réutilisables dans src/components/

📚 API Reference

Fonctions Fetch

getFetch<T>(route, headers?)

1const response = await getFetch<User[]>("/users");
2// response: ApiResponse<User[]>

postFetch<T>(route, data, headers?)

1const response = await postFetch<User>("/users", { name: "John" });
2// Support automatique FormData et JSON

putFetch<T>(route, data, headers?)

1const response = await putFetch<User>("/users/123", updateData);

deleteFetch<T>(route, headers?)

1const response = await deleteFetch("/users/123");

withAuth(token, headers?)

1const headers = withAuth(userToken, { "Custom-Header": "value" });
2// Retourne: { Authorization: 'Bearer token', 'Custom-Header': 'value' }

Hook useAuth

1const {
2  isAuthenticated, // boolean - État d'authentification
3  token, // string | null - Token d'accès
4  refreshToken, // string | null - Token de refresh
5  user, // User | null - Données utilisateur
6  login, // (token, refreshToken?, user?) => void
7  logout, // () => void
8  verifyToken, // (token?) => Promise<boolean>
9  refreshAccessToken, // () => Promise<boolean>
10  updateUser, // (user) => void
11  loading, // boolean - État de chargement
12  config, // AuthConfig - Configuration actuelle
13} = useAuth();

Types principaux

1interface ApiResponse<T> {
2  status: number;
3  data: T | null;
4  error?: string;
5  success: boolean;
6}
7
8interface User {
9  id: string;
10  email: string;
11  name?: string;

12  [key: string]: any;
13}
14
15interface AuthConfig {
16  endpoints: {
17    verify: string;
18    refresh?: string;
19  };
20  storage: {
21    tokenKey: string;
22    refreshTokenKey?: string;
23    userKey?: string;
24  };
25  autoVerify: boolean;
26}

💡 Exemples pratiques

Gestion d'erreurs robuste

1const handleApiCall = async () => {
2  const response = await getFetch<Data>("/data");
3
4  if (response.success) {
5    // Succès - response.data est typé
6    setData(response.data);
7  } else {
8    // Erreur - afficher le message
9    setError(response.error);
10
11    // Gestion spécifique par code de statut
12    switch (response.status) {
13      case 401:
14        // Token expiré - redirection login
15        logout();
16        break;
17      case 403:
18        // Pas d'autorisation
19        setError("Accès refusé");
20        break;
21      default:
22        setError("Erreur serveur");
23    }
24  }
25};

Refresh automatique des tokens

1// Le refresh est automatique, mais peut être manuel
2const { refreshAccessToken } = useAuth();
3
4const handleExpiredToken = async () => {
5  const success = await refreshAccessToken();
6  if (success) {
7    // Token renouvelé, refaire la requête
8    await retryApiCall();
9  } else {
10    // Échec du refresh, déconnexion
11    logout();
12  }
13};

Configuration pour différents backends

1// Pour une API REST classique
2<AuthProvider config={{
3  endpoints: {
4    verify: "/api/auth/me",
5    refresh: "/api/auth/refresh"
6  }
7}} />
8
9// Pour Firebase ou services tiers
10<AuthProvider config={{
11  endpoints: {
12    verify: "/api/user/profile"
13  },
14  autoVerify: false // Gérer manuellement
15}} />
16
17// Pour des clés de stockage personnalisées
18<AuthProvider config={{
19  storage: {
20    tokenKey: "jwt_token",
21    userKey: "user_data"
22  }
23}} />

🛠️ Scripts & Build

1npm run build
2# Drag & drop du dossier `dist/` sur Netlify

1npm i -g vercel
2vercel --prod

1npm run build
2# Configurer GitHub Actions avec le workflow .github/workflows/deploy.yml

1FROM node:18-alpine
2WORKDIR /app
3COPY package*.json ./
4RUN npm ci --only=production
5COPY dist/ ./dist/
6EXPOSE 3000
7CMD ["npx", "serve", "-s", "dist", "-l", "3000"]

🤝 Contribution

Les contributions sont les bienvenues ! 🎉

🐛 Signaler un problème

• Bug : Créer une issue
• Feature Request : Proposer une amélioration
• Question : Démarrer une discussion

📝 Changelog

v1.0.0 (Latest)

• ✨ Initial release
• 🔐 JWT Authentication system
• 🌐 Complete API client with TypeScript
• 🛡️ Protected routes HOC
• 📖 Comprehensive documentation
• 🎨 Bootstrap 5 integration

📄 Licence

MIT License - voir le fichier LICENSE pour plus de détails.