Guide de Démarrage Développeur - Kit'Asso Documentation

Vue d’ensemble

Ce guide vous permet de configurer Kit’Asso en local et de commencer à développer rapidement. En 10 minutes, vous aurez un environnement fonctionnel avec base de données Supabase et serveur de développement Vite. Prérequis :

Node.js 18+ installé
npm ou yarn
Compte Supabase (gratuit)
Git
Éditeur de code (VS Code recommandé)

Installation en 10 minutes

Étape 1 : Cloner le projet

# Cloner le repository
git clone https://github.com/Lucdidi3514/assopedia-v2
cd kit-asso

# Vérifier Node.js version
node --version  # Doit être 18+

Étape 2 : Installer les dépendances

# Installation
npm install

# Temps estimé : 2-3 minutes

Dépendances principales installées :

React 18 + TypeScript
Vite 6.3.5
Supabase Client
React Router v6
React Hook Form + Zod
Tailwind CSS
Lucide React (icons)

Étape 3 : Configuration Supabase

3.1 Créer un projet Supabase

Aller sur supabase.com
Cliquer sur “New Project”
Remplir les informations :
- Name: kit-asso-dev
- Database Password: (générer un mot de passe fort)
- Region: Europe West (ou proche de vous)
Attendre ~2 minutes (création du projet)

3.2 Récupérer les credentials Dans le dashboard Supabase :

Aller dans Settings > API
Copier Project URL (commence par https://xxxxx.supabase.co)
Copier anon public key (longue chaîne JWT)

3.3 Configurer les variables d’environnement

# Créer le fichier .env
cp .env.example .env

# Éditer .env avec vos credentials
nano .env  # ou code .env

Contenu de .env :

VITE_SUPABASE_URL=https://xxxxx.supabase.co
VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Étape 4 : Initialiser la base de données

4.1 Créer les tables (via SQL Editor)

Dans Supabase Dashboard → SQL Editor
Copier le contenu de supabase/migrations/ dans l’ordre
Exécuter migration par migration

Alternative : Script automatique

# Si Supabase CLI installé
npm install -g supabase
supabase link --project-ref your-project-ref
supabase db push

Tables créées (13) :

tools, categories, filters, tool_features
workflows, workflow_steps
tool_packs, pack_tools
quizzes, quiz_questions, quiz_answers, quiz_recommendations, quiz_responses
site_assets

4.2 Créer les Storage Buckets Dans Storage > New Bucket :

Nom : tool_logos, Public : ✅, File size limit : 2MB
Nom : site_assets, Public : ✅, File size limit : 5MB

4.3 Insérer des données de test (optionnel)

-- Créer une catégorie
INSERT INTO categories (name) VALUES ('Communication');

-- Créer un outil de test
INSERT INTO tools (name, description, pricing_tier, category_id)
VALUES (
  'Notion',
  'Outil tout-en-un pour la gestion de projets',
  'Freemium',
  (SELECT id FROM categories WHERE name = 'Communication')
);

Étape 5 : Lancer le serveur de développement

# Démarrer Vite
npm run dev

# Serveur disponible sur http://localhost:5173

Ce qui se passe :

Vite compile le code TypeScript
Tailwind génère les styles CSS
Hot Module Replacement (HMR) activé
Navigateur s’ouvre automatiquement

Vérification :

✅ Page d’accueil affichée
✅ Pas d’erreur dans la console
✅ Connexion Supabase OK (vérifier Network tab)

Étape 6 : Créer un compte admin

6.1 Via Supabase Dashboard

Authentication > Users > Add user
Email : [email protected]
Password : votre-mot-de-passe
Auto Confirm : ✅

6.2 Se connecter

Aller sur http://localhost:5173/login
Entrer email + password
Redirection vers /admin
✅ Dashboard admin accessible

Structure du projet

Aperçu des dossiers

kit-asso/
├── src/
│   ├── api/              # Couche d'abstraction Supabase
│   ├── components/       # Composants UI réutilisables
│   ├── features/         # Modules par domaine métier
│   ├── hooks/            # Custom React hooks
│   ├── lib/              # Utilitaires core (auth, storage)
│   ├── pages/            # Pages route
│   ├── types/            # Définitions TypeScript
│   ├── utils/            # Helpers (icons, colors, sanitization)
│   ├── App.tsx           # Root component
│   ├── main.tsx          # Entry point
│   └── router.tsx        # React Router config
├── supabase/
│   └── migrations/       # 43 fichiers SQL
├── public/               # Assets statiques
├── .env                  # Variables d'environnement (à créer)
├── package.json
├── vite.config.ts
└── tailwind.config.js

Premiers pas dans le code

1. Comprendre l’architecture API Layer

Fichier : src/api/tools.ts

import { supabase } from './client';
import { handleSupabaseError } from './base';

export const toolsApi = {
  // Lister tous les outils
  async list() {
    const { data, error } = await supabase
      .from('tools')
      .select(`
        *,
        category:categories(name),
        features:tool_features(filter:filters(*))
      `);

    if (error) throw handleSupabaseError(error);
    return data;
  },

  // Créer un outil
  async create(tool: ToolInsert) {
    const { data, error } = await supabase
      .from('tools')
      .insert(tool)
      .select()
      .single();

    if (error) throw handleSupabaseError(error);
    return data;
  }
};

Utilisation dans un composant :

import { toolsApi } from '@/api';

function ToolsList() {
  const [tools, setTools] = useState([]);

  useEffect(() => {
    toolsApi.list().then(setTools);
  }, []);

  return (
    <div>
      {tools.map(tool => (
        <div key={tool.id}>{tool.name}</div>
      ))}
    </div>
  );
}

2. Utiliser les Custom Hooks

Hook : src/hooks/useAppData.ts

import { useAppData } from '@/hooks/useAppData';

function HomePage() {
  const { tools, workflows, packs, loading, error } = useAppData();

  if (loading) return <LoadingSpinner />;
  if (error) return <ErrorMessage />;

  return (
    <div>
      <h1>Catalogue : {tools.length} outils</h1>
      <ToolsGrid tools={tools} />
    </div>
  );
}

Avantages :

Gestion du loading automatique
Retry logic intégré
Fallback data si erreur réseau

3. Créer un nouveau composant

Fichier : src/components/ToolCard.tsx

import { Tool } from '@/types/database';
import { ToolLogo } from './ToolLogo';
import { PricingBadge } from './PricingBadge';

interface ToolCardProps {
  tool: Tool;
  onClick?: () => void;
}

export function ToolCard({ tool, onClick }: ToolCardProps) {
  return (
    <div 
      onClick={onClick}
      className="bg-white rounded-lg p-4 shadow-md hover:shadow-lg transition-shadow cursor-pointer"
    >
      <ToolLogo url={tool.logo_url} name={tool.name} size="md" />
      <h3 className="font-semibold mt-3">{tool.name}</h3>
      <p className="text-sm text-gray-600 mt-1">{tool.description}</p>
      <PricingBadge tier={tool.pricing_tier} className="mt-3" />
    </div>
  );
}

4. Ajouter une nouvelle route

Fichier : src/router.tsx

import { createBrowserRouter } from 'react-router-dom';
import { NewPage } from './pages/NewPage';

export const router = createBrowserRouter([
  {
    path: '/',
    element: <App />,
    children: [
      // ... routes existantes
      {
        path: '/nouvelle-page',
        element: <NewPage />
      }
    ]
  }
]);

Commandes de développement

Scripts npm disponibles

# Développement
npm run dev              # Serveur dev avec HMR

# Build
npm run build            # Build production
npm run preview          # Preview du build

# Tests
npm test                 # Run tests once
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report

# Qualité de code
npm run lint             # ESLint check
npm run typecheck        # TypeScript check

# Analyse
npm run analyze          # Bundle size analysis

Workflow de développement quotidien

# 1. Pull dernières modifications
git pull origin main

# 2. Installer nouvelles dépendances (si package.json modifié)
npm install

# 3. Lancer dev server
npm run dev

# 4. Développer avec HMR
# ... modifier le code, sauvegarder, voir les changements instantanément

# 5. Vérifier la qualité avant commit
npm run lint
npm run typecheck
npm test

# 6. Commit et push
git add .
git commit -m "feat: nouvelle fonctionnalité"
git push

Debugging

Logs Supabase

Activer les logs détaillés :

// src/api/client.ts
import { createClient } from '@supabase/supabase-js';

export const supabase = createClient(
  import.meta.env.VITE_SUPABASE_URL,
  import.meta.env.VITE_SUPABASE_ANON_KEY,
  {
    auth: {
      persistSession: true,
      autoRefreshToken: true,
      detectSessionInUrl: true
    },
    // Activer les logs en dev
    global: {
      headers: {
        'x-client-info': 'kit-asso-dev'
      }
    }
  }
);

Vérifier les requêtes :

Chrome DevTools > Network > Filter: supabase
Voir les queries SQL exécutées
Vérifier les codes de statut (200 OK, 401 Unauthorized)

React DevTools

Installation :

# Extension Chrome/Firefox
# Rechercher "React Developer Tools"

Utilisation :

Ouvrir DevTools > Components
Inspecter la hiérarchie de composants
Voir les props/state en temps réel
Profiler les rendus

Erreurs fréquentes

Erreur : “Invalid API key”

# Vérifier .env
cat .env

# Relancer le serveur
npm run dev

Erreur : “Table doesn’t exist”

# Vérifier les migrations Supabase
# Dashboard > SQL Editor > Vérifier les tables

Erreur : “RLS policy violation”

# Se connecter en tant qu'admin
# Ou vérifier les policies dans /database/rls

Ressources

API Layer

Guide complet d’utilisation de l’API

Hooks Custom

Documentation des hooks métier

Composants UI

Catalogue des composants réutilisables

Conventions

Standards de code et best practices

Développement

​Vue d’ensemble

​Installation en 10 minutes

​Étape 1 : Cloner le projet

​Étape 2 : Installer les dépendances

​Étape 3 : Configuration Supabase

​Étape 4 : Initialiser la base de données

​Étape 5 : Lancer le serveur de développement

​Étape 6 : Créer un compte admin

​Structure du projet

​Aperçu des dossiers

​Premiers pas dans le code

​1. Comprendre l’architecture API Layer

​2. Utiliser les Custom Hooks

​3. Créer un nouveau composant

​4. Ajouter une nouvelle route

​Commandes de développement

​Scripts npm disponibles

​Workflow de développement quotidien

​Debugging

​Logs Supabase

​React DevTools

​Erreurs fréquentes

​Ressources