Gestion Cadeaux — une app React/FastAPI pour les listes de Noël

Chaque année, c est la même chose : qui offre quoi ? à qui ? est-ce que quelqu un a déjà acheté le cadeau de mamie ? J ai fini par écrire une petite app pour répondre à ces questions une bonne fois pour toutes.

Le concept

Une app web où chacun peut :

  • Créer des listes de cadeaux (Noël, anniversaire, enterrement de vie de garçon…)
  • Ajouter des items avec un nom, une description, un lien et un prix
  • Marquer un cadeau comme acheté (avec le nom de l acheteur)
  • Partager une liste par un lien pour que les autres puissent voir et cocher
  • Filtrer et trier les cadeaux de toutes les façons possibles
  • Voir le total dépensé en temps réel

Le tout sans création de compte, sans pub, sans inscription. Juste un prénom pour commencer.

Stack technique

  • Frontend : React 19, Create React App, CSS vanilla (thème sombre)
  • Backend : FastAPI (Python 3), PostgreSQL, psycopg2
  • Proxy : Nginx → Nginx Proxy Manager (proxy inverse avec SSL Let s Encrypt)
  • Hébergement : VM sur homelab Unraid

L API est toute petite — une dizaine de routes REST, un health check, et c est tout. Pas de framework CSS, pas de lib externe, pas de State Management (les useState de React suffisent amplement pour une app de cette taille).

Ce qui a changé en cours de route

V1 : le prototype

La première version tenait dans un seul fichier HTML avec du JS inline et des alert() pour tout feedback utilisateur. Les listes étaient stockées dans un fichier JSON sur le serveur. Ça marchait, mais c était moche et ça tenait pas la route avec plusieurs utilisateurs simultanés.

V2 : React + API

Réécriture complète : frontend React avec Create React App, backend FastAPI avec PostgreSQL, déploiement via tar+ssh sur le serveur nginx de l homelab.

Cette version apportait :

  • Interface sobre avec thème sombre
  • Barre de recherche et tri (par date, nom, prix, non achetés d abord)
  • Ajout d items sans rechargement de page
  • Prix total + total acheté
  • Partage par lien avec un token unique par liste
  • Confirmations modales et notifications toast (plus de alert())

V3 : multi-utilisateur

La grosse demande qui a tout changé : le multi-utilisateur. Chaque personne qui ouvre l app choisit son prénom sur un écran d accueil stylé, et ne voit que ses propres listes. Pour accéder à une liste partagée, il suffit du lien — pas de création de compte.

Côté base de données, ça a demandé deux colonnes supplémentaires :

ALTER TABLE cadeaux_liste ADD COLUMN created_by VARCHAR(100);
ALTER TABLE cadeaux_item ADD COLUMN created_by VARCHAR(100);

Et côté API, un paramètre ?user= dans la route GET /listes pour filtrer les listes par créateur.

Le front end a aussi gagné un système de contexte React (UserContext) qui persiste le prénom dans localStorage, un écran de login, et une section “Accéder à une liste partagée” avec un input pour coller le lien ou le token.

Déploiement

Le déploiement se fait en deux commandes :

npm run build
tar cz -C build . | ssh serveur 'tar xzf - -C /chemin/nginx/projets/gestion-cadeaux/'

Le backend FastAPI tourne avec systemd sur une VM dédiée. Le tout est proxifié par Nginx Proxy Manager qui termine le SSL Let s Encrypt et forwarde les requêtes.

Ce que j aurais fait différemment

  • Create React App est lourd pour une app de cette taille. Le build génère 65 kB de JS + 2 kB de CSS. Un bundler plus léger comme Vite ou Preact aurait été plus adapté.
  • Pas de migration automatisée : la migration DB est faite au démarrage de l app avec un ALTER TABLE ... ADD COLUMN IF NOT EXISTS. C est un peu rustique mais ça marche.
  • Pas de tests : l app est utilisée par ma famille et moi, pas par des millions de users. Les tests sont faits “en production” 😅

Liens