Prise en main rapide

Fichiers source

Cette page est générée à partir des fichiers source suivants :

• README.md
• package.json
• .env.example
• next.config.js
• src/lib/hooks/useNotification.ts
• src/components/DailyChallenge.tsx
• src/components/AchievementCard.tsx
• src/components/ActionItemsList.tsx
• src/app/progress/client-progress.tsx
• src/components/ComprehensionTest.tsx

Ce guide de démarrage rapide présente la procédure d'installation, de configuration et de lancement de la plateforme d'apprentissage gamifiée pour la rédaction, destinée aux élèves de sixième. Le projet repose sur une architecture Next.js sans backend, avec stockage local des données.

Prérequis et Installation

Technologies Nécessaires

Le projet utilise une stack moderne basée sur Next.js 14 avec l'App Router. Les technologies principales incluent TypeScript pour le typage statique, Tailwind CSS pour les styles, Zustand pour la gestion d'état, et Framer Motion pour les animations (README.md:13-21).

Les navigateurs compatibles incluent Chrome 60+, Firefox 55+, Safari 12+ et Edge 79+ (README.md:104-109).

Procédure d'Installation

L'installation des dépendances s'effectue via l'un des gestionnaires de paquets suivants :

bash
1# Installation avec npm
2npm install
3
4# Installation avec yarn
5yarn install
6
7# Installation avec pnpm
8pnpm install

Ces commandes installent l'ensemble des dépendances définies dans le fichier package.json, incluant les composants Radix UI, les utilitaires Tailwind, et les bibliothèques de gestion d'état (package.json:12-42).

Lancement du Serveur de Développement

Une fois les dépendances installées, le serveur de développement se lance avec la commande :

bash
1# Avec npm
2npm run dev
3
4# Avec yarn
5yarn dev
6
7# Avec pnpm
8pnpm dev

Le serveur démarre sur le port 3000 par défaut. L'application devient accessible à l'adresse http://localhost:3000 dans le navigateur (README.md:34-43). Les scripts disponibles incluent également build, start et lint pour la production et l'analyse de code (package.json:6-11).

Configuration de lEnvironnement

Variables d'Environnement

Le projet utilise des variables d'environnement optionnelles pour la configuration de l'API AI. Un fichier .env.example sert de modèle à copier vers .env.local (.env.example:1-11).

Configuration AI et Personnalisation

L'application supporte le modèle BYOK (Bring Your Own Key) pour l'API AI. Les utilisateurs peuvent configurer leur propre clé API directement dans la page de paramètres de l'application, sans nécessiter de modification du code source (README.md:93-99).

La plateforme supporte également des endpoints API personnalisés compatibles avec le format OpenAI, tels que DeepSeek ou Moonshot. Cette flexibilité permet d'utiliser différents fournisseurs de services AI sans modification architecturale (README.md:91).

Pour personnaliser le contenu des outils d'écriture, il suffit de modifier le fichier src/data/tools.ts pour ajouter de nouveaux exercices et exemples (README.md:100-102).

Configuration Next.js

Le fichier next.config.js définit la configuration optimisée pour le déploiement Vercel. Les options incluent le mode strict React, la minification SWC, et une configuration webpack spécifique pour gérer les modules .mjs (next.config.js:1-20).

javascript
1// Configuration clé dans next.config.js
2const nextConfig = {
3  reactStrictMode: true,
4  swcMinify: true,
5  images: {
6    unoptimized: true
7  }
8}

Structure du Projet

Organisation des Répertoires

Le projet suit la structure standard de Next.js 14 avec l'App Router. L'organisation modulaire facilite la maintenance et l'extension du code (README.md:75-85).

src/
├── app/           # Pages Next.js App Router
├── components/    # Composants réutilisables
├── data/          # Données statiques
├── lib/           # Utilitaires et gestion d'état
├── types/         # Définitions TypeScript
└── styles/        # Styles globaux

Architecture Sans Backend

L'application adopte une architecture entièrement côté client, sans serveur backend dédié. Toutes les données utilisateur sont stockées dans le localStorage du navigateur, incluant la progression d'apprentissage et les rédactions (README.md:87-90).

Cette approche présente plusieurs avantages :

• Déploiement simplifié sur des plateformes statiques
• Aucune gestion de base de données serveur
• Fonctionnement hors ligne partiel
• Confidentialité des données préservée localement

Dépendances Principales

Le fichier package.json liste les dépendances essentielles au fonctionnement de l'application (package.json:12-42).

Fonctionnalités Principales

Défis Quotidiens et Gamification

Le composant DailyChallenge implémente le système de défis journaliers qui constitue le cœur de l'expérience gamifiée. Chaque défi affiche une tâche d'écriture avec la date courante et le nombre de jours consécutifs accomplis (src/components/DailyChallenge.tsx:1-50).

typescript
1// Extrait du système de défis quotidiens
2interface DailyChallengeProps {
3  challenge: DailyChallenge;
4  onSwap?: () => void;
5  onMakeup?: () => void;
6}

Le système propose plusieurs interactions :

• Aller compléter : Redirection vers l'éditeur d'écriture
• Changer de défi : Option pour obtenir un nouveau sujet
• Rattrapage : Possibilité de compléter les jours manqués

L'interface utilise un design gradient avec des couleurs Morandi pour une expérience visuelle apaisante (src/components/DailyChallenge.tsx:26-40).

Système de Progression et Achievements

Le système de progression suit les accomplissements de l'utilisateur à travers plusieurs métriques. La page client-progress affiche le nombre d'outils maîtrisés, le score total accumulé et la quantité de rédactions produites (src/app/progress/client-progress.tsx:1-50).

typescript
1// Calcul de la progression
2const completedCount = progress.levels.filter(level => level.completed).length;
3const totalTools = tools.length;
4const progressPercentage = Math.round((completedCount / totalTools) * 100);

Les achievements sont affichés via le composant AchievementCard, qui présente chaque récompense avec son titre, description et date d'obtention (src/components/AchievementCard.tsx:1-34).

Liste d'Actions et Tâches

Le composant ActionItemsList gère les listes de tâches actionnables. Chaque élément peut être marqué comme complété, avec un suivi visuel du progrès (src/components/ActionItemsList.tsx:1-50).

Les fonctionnalités incluent :

• Toggle interactif pour marquer les tâches
• Compteur de progression (X/Y complétés)
• Message de félicitations lors de l'achèvement total

Système de Notifications

Le hook useNotification fournit un système de notifications temporaires avec support pour les types success, error et warning. Les notifications disparaissent automatiquement après un délai configurable (5 secondes par défaut) (src/lib/hooks/useNotification.ts:1-29).

Déploiement sur Vercel

Étapes de Déploiement

Le projet est préconfiguré pour un déploiement simplifié sur Vercel. La procédure standard comprend (README.md:65-74) :

1. Pousser le code vers un dépôt GitHub
2. Se connecter sur Vercel et importer le projet
3. Sélectionner le dépôt GitHub correspondant
4. Vercel détecte automatiquement la configuration Next.js
5. Cliquer sur "Deploy" pour lancer le déploiement

Build de Production

Avant le déploiement, il est recommandé de tester le build de production localement :

bash
1# Construction de la version production
2npm run build
3
4# Démarrage du serveur production
5npm start

Ces commandes permettent de vérifier que l'application se compile correctement et fonctionne comme prévu en environnement de production (README.md:45-63).

Vérification et Validation

Vérification du Serveur de Développement

Après avoir exécuté npm run dev, le terminal devrait afficher une sortie similaire à :

▲ Next.js 14.2.0
- Local:        http://localhost:3000
- Environments: .env.local

L'accès à http://localhost:3000 doit afficher la page d'accueil de l'application avec les 7 outils d'écriture gamifiés.

Validation des Fonctionnalités

Pour confirmer le bon fonctionnement de l'application :

1. Navigation : Vérifier l'accès aux différentes pages via le menu
2. Stockage local : Créer une rédaction et rafraîchir la page pour confirmer la persistance
3. Progression : Compléter un exercice et vérifier la mise à jour du score
4. Responsive : Tester sur différentes tailles d'écran

Problèmes Courants et Solutions

Erreur de Port Déjà Utilisé

Symptôme : Le serveur ne démarre pas avec un message Port 3000 is already in use.

Solution :

bash
1# Tuer le processus utilisant le port 3000
2# Sur macOS/Linux
3lsof -i :3000
4kill -9 <PID>
5
6# Ou utiliser un port alternatif
7PORT=3001 npm run dev

Problèmes de Dépendances

Symptôme : Erreurs de modules non trouvés après npm install.

Solution :

bash
1# Supprimer node_modules et réinstaller
2rm -rf node_modules package-lock.json
3npm install

Variables d'Environnement Non Prises en Compte

Symptôme : L'API AI ne fonctionne pas malgré la configuration.

Solution :

• Vérifier que le fichier s'appelle .env.local et non .env.example
• Redémarrer le serveur de développement après modification
• Les variables doivent commencer par NEXT_PUBLIC_ pour être accessibles côté client

Erreur de Build Vercel

Symptôme : Échec du build avec erreur JavaScript sur les modules .mjs.

Solution : La configuration webpack dans next.config.js gère ce cas. Vérifier que le fichier de configuration est correctement déployé (next.config.js:10-17).

Prochaines Étapes

Après avoir réussi l'installation et la vérification de base, les utilisateurs peuvent :

1. Explorer les outils d'écriture : Naviguer dans les 7 niveaux de difficulté progressive
2. Configurer l'API AI : Ajouter une clé API dans les paramètres pour activer la correction automatique
3. Personnaliser le contenu : Modifier src/data/tools.ts pour adapter les exercices
4. Consulter la documentation : Se référer aux sections avancées pour les configurations détaillées

Pour une utilisation approfondie des fonctionnalités de gamification et de suivi de progression, consulter le guide d'utilisation complet qui détaille chaque composant et son intégration dans le flux d'apprentissage.