Cours Vibe coding avec Claude Code · Module 4: Clone d'Instagram

Silence sur le pont : une recherche avec debounce

10 min de lecture ·
Dans cette leçon8

La galerie grossit à chaque voyage et il devient de plus en plus difficile d'y retrouver une seule photo. Il est temps d'ajouter une recherche dans les légendes. C'est le serveur qui cherchera, car quand les photos seront dans une base de données, le navigateur ne les recevra pas toutes d'un coup. Et chaque question au serveur a un coût : chez nous, la seconde et demie de la leçon 3_4.

Le problème : six questions pour un seul mot

Le capitaine tape "coffre". Le champ change six fois : "c", "co", "cof" et ainsi de suite. Si chaque changement envoie une question au serveur, le serveur cherche six fois, cinq résultats ne servent à personne, et le squelette clignote à chaque lettre.

La solution s'appelle le debouncing : tu attends, avant d'envoyer la question, que la personne qui tape fasse une pause. Chaque nouvelle lettre annule le compte à rebours et le relance à zéro, donc la question ne part qu'après 300 millisecondes de silence. C'est comme le timonier qui ne tourne pas la barre à chaque coup de vent, mais attend que le vent se stabilise.

La phrase ira aussi dans l'adresse de la page, sous la forme ?q=coffre. Ce morceau d'adresse après le point d'interrogation est un paramètre de recherche (search param). Grâce à lui, on peut envoyer le lien des résultats à l'équipage, et la page se souvient de ce que tu cherchais après un rechargement.

Demande pour Claude Code

La demande dit qui cherche, où se trouve le champ, combien dure le silence et ce qu'il ne faut pas faire :

Demande pour Claude Code :

Ajoute à Treasure Gallery une recherche dans les légendes des photos. La
phrase va dans l'adresse sous la forme ?q=, et c'est le serveur qui filtre :
getPhotos(query) dans @lib/photos.ts, sans tenir compte des majuscules. Le
champ se trouve au-dessus de la grille, dans un nouveau Client Component
components/SearchBox.tsx, et change l'adresse avec router.replace seulement
après 300 ms sans frappe (debounce). Pas de nouveau paquet et pas de setState
dans useEffect. Une phrase vide retire q de l'adresse. Quand rien ne
correspond, écris qu'aucune photo n'a cette légende. N'ajoute ni memo, ni
useMemo, ni useCallback. Termine par npm run build et npm run lint.

Les interdits ont des raisons. Un nouveau paquet pour le debounce, c'est du code d'un autre dans le projet pour quelques lignes. Mettre l'état directement dans un effet enfreint la règle react-hooks/set-state-in-effect, et npm run lint le refusera. D'ailleurs, l'effet n'est pas nécessaire ici : la question part parce que quelqu'un tape, et la réaction à un événement revient à une fonction de gestion d'événement. Tu en apprendras davantage sur la mémoïsation à la fin de la leçon.

Ce que Claude a écrit : le serveur cherche

Ouvre lib/photos.ts dans Cursor. La fonction de la leçon 3_4 a reçu un paramètre :

export async function getPhotos(query = ""): Promise<Photo[]> {
  await new Promise((resolve) => setTimeout(resolve, 1500));
  const phrase = query.trim().toLocaleLowerCase("fr");
  return photos.filter((photo) =>
    photo.caption.toLocaleLowerCase("fr").includes(phrase),
  );
}

query = "" est une valeur par défaut, donc un appel sans phrase fonctionne comme avant. toLocaleLowerCase("fr") met les lettres en minuscules selon les règles du français, et "ENTERRÉ" trouvera "enterré". filter garde les photos dont la légende contient la phrase, et une phrase vide correspond à toutes les légendes. Le retard est resté : c'est notre faux coût de chaque question.

La page app/gallery/page.tsx lit la phrase dans l'adresse :

export default async function GalleryPage({ searchParams }: PageProps<"/gallery">) {
  const { q } = await searchParams;
  const query = typeof q === "string" ? q : "";

searchParams contient les paramètres de l'adresse, que Next.js donne à la page sous forme de promesse, d'où le await devant. PageProps<"/gallery"> est un type que Next.js génère lui-même pour cette route, sans import. Le paramètre peut arriver comme un texte, comme une liste ou pas du tout, donc typeof q === "string" ne garde que le texte et remplace le reste par une phrase vide.

Sous l'en-tête se trouvent le champ et la grille :

<SearchBox initialQuery={query} />

<Suspense key={query} fallback={<GallerySkeleton />}>
  <PhotoGrid query={query} />
</Suspense>

PhotoGrid transmet la phrase à getPhotos et, si le résultat est vide alors qu'il y a une phrase, écrit qu'aucune photo n'a cette légende, au lieu d'inviter à ajouter la première. Le key={query} est nouveau. Pour React, chaque phrase est une nouvelle frontière Suspense, donc le squelette revient à chaque recherche, et Gallery repart de zéro avec des photos fraîches. Tu verras pourquoi c'est important dans la revue.

Ce que Claude a écrit : le champ avec debounce

Ouvre components/SearchBox.tsx. Le fichier commence par "use client", car le champ réagit à la frappe. Le compte à rebours est gardé par un useRef de la leçon 2_5, et la fonction de gestion d'événement le réinitialise :

const timer = useRef<ReturnType<typeof setTimeout> | null>(null);

const handleChange = (value: string) => {
  if (timer.current) clearTimeout(timer.current);
  timer.current = setTimeout(() => {
    const phrase = value.trim();
    router.replace(phrase ? `${pathname}?q=${encodeURIComponent(phrase)}` : pathname);
  }, 300);
};

Chaque lettre commence par annuler le compte à rebours précédent avec clearTimeout, puis en lance un nouveau. Seules 300 millisecondes de silence laissent passer la phrase vers router.replace, qui change l'adresse sans ajouter d'entrée à l'historique du navigateur, donc le bouton Retour ne recule pas d'une lettre. router et pathname (le chemin actuel, ici /gallery) viennent des hooks useRouter et usePathname de next/navigation. encodeURIComponent transforme les espaces, les lettres accentuées et les caractères & en une écriture sûre dans l'adresse. On utilise un ref et non une variable let ordinaire, car le ref survit aux rendus suivants ; une variable ordinaire serait déjà refusée par npm run lint avec la règle react-hooks/immutability.

Sous la fonction se trouve le seul effet du fichier :

useEffect(() => {
  return () => {
    if (timer.current) clearTimeout(timer.current);
  };
}, []);

Il ne met aucun état à jour, il fait seulement le ménage. Si quelqu'un tape une lettre et quitte aussitôt la page, le compte à rebours sans nettoyage continue de tourner et, 300 millisecondes plus tard, le ramène dans la galerie ; nous l'avons vérifié. Le nettoyage au démontage annule le compte à rebours avec le composant. Le champ lui-même a defaultValue={initialQuery}, c'est-à-dire qu'il démarre avec la phrase de l'adresse, et un onChange qui appelle handleChange.

La revue du capitaine

Lance npm run dev, ouvre localhost:3000/gallery et vérifie :

  1. Une question par mot. La preuve est le terminal de npm run dev : Next.js y affiche chaque requête vers la page. Tape "coffre" à un rythme normal et compte les nouvelles lignes. Il doit y en avoir une, GET /gallery?q=coffre 200. Si Claude oublie clearTimeout, le debounce ne fait que retarder les questions et tu en verras six :
GET /gallery?q=c 200 in 1529ms (next.js: 1.8ms, application-code: 1527ms)
GET /gallery?q=co 200 in 1519ms (next.js: 2ms, application-code: 1517ms)
GET /gallery?q=cof 200 in 1520ms (next.js: 8ms, application-code: 1512ms)
GET /gallery?q=coff 200 in 1521ms (next.js: 1.7ms, application-code: 1519ms)
GET /gallery?q=coffr 200 in 1517ms (next.js: 1.2ms, application-code: 1516ms)
GET /gallery?q=coffre 200 in 1511ms (next.js: 2ms, application-code: 1509ms)

Le build et le lint passent dans les deux versions, donc compte les lignes au lieu de croire l'affirmation "le debounce marche".

  1. Le key sur Suspense. C'est une erreur typique de l'agent : une frontière sans clé. Nous avons regardé ce qui se passe alors. Pendant la frappe, le squelette ne s'affiche pas, car à chaque changement d'adresse React laisse à l'écran les anciens résultats, et quand le serveur répond, la grille a toujours les six photos. Gallery a pris les photos dans un état via useState(photos), et la valeur de départ n'est calculée qu'au premier rendu. Après un rechargement de la page, le résultat est correct, pendant la frappe il ne l'est pas, et c'est ce qui trompe le plus. Dans le diff, cherche key={query}.
  2. Les accents et le résultat vide. Tape "ENTERRÉ" en majuscules : la photo dont la légende est "Ici, nous avons enterré le coffre" doit apparaître. Tape "kraken" : la phrase disant qu'aucune photo n'a cette légende doit s'afficher, et non l'invitation à ajouter la première photo.
  3. Le lien vers les résultats. Copie l'adresse avec ?q= dans un nouvel onglet : les résultats et la phrase dans le champ sont les mêmes. Efface le champ : l'adresse perd ?q=.

Pour finir, trouve dans le résultat de npm run build la ligne /gallery. Elle est maintenant précédée de ƒ (Dynamic) : la page utilise les paramètres de l'adresse, donc elle est créée à chaque visite, et le squelette de la leçon 3_4 est visible même après le build.

Debounce ou useDeferredValue

Le debounce économise le serveur. Quand tu filtres des photos que le navigateur a déjà, la documentation de React recommande autre chose : useDeferredValue. Le hook renvoie une copie retardée de la valeur, et React dessine la liste pour la nouvelle phrase en arrière-plan et interrompt ce travail quand une autre lettre arrive :

const [query, setQuery] = useState("");
const deferredQuery = useDeferredValue(query);
const phrase = deferredQuery.trim().toLocaleLowerCase("fr");
const visible = items.filter((photo) =>
  photo.caption.toLocaleLowerCase("fr").includes(phrase),
);

Le champ affiche query tout de suite, et la liste utilise deferredQuery. Il n'y a ici aucun nombre fixe de millisecondes : sur un ordinateur rapide, le retard est imperceptible, sur un lent, la liste reste un peu en arrière par rapport au champ. La documentation souligne aussi que useDeferredValue ne réduit pas à lui seul le nombre de requêtes réseau. D'où une règle simple : tu interroges un serveur, c'est le debounce ; tu dessines dans le navigateur, c'est useDeferredValue. On peut aussi combiner les deux techniques.

La mémoïsation par précaution

La demande interdisait trois outils que Claude aime ajouter "pour la performance". React.memo saute le nouveau rendu d'un composant quand ses props n'ont pas changé. useMemo mémorise le résultat d'un calcul, et useCallback mémorise la fonction elle-même, pour que ce soit la même fonction au rendu suivant. Chacun ajoute du code et des dépendances à surveiller, et avec six photos, aucun ne va plus vite. Je te recommande cette règle : mesure d'abord, par exemple dans l'onglet Profiler des React DevTools, optimise ensuite. Si Claude ajoute l'un d'eux sans mesure, demande-lui ce qu'il a mesuré.

Étape suivante

Avant de faire le commit, lance /code-review de la leçon 2_9 et lis le rapport dans Cursor. Puis le commit, par exemple "Galerie : recherche dans les légendes avec debounce", et une petite extension :

Dans @components/PhotoGrid.tsx, au-dessus de la grille, affiche combien de
photos correspondent à la phrase, avec le bon accord du pluriel : 1 photo,
2 photos. Seulement quand la phrase n'est pas vide. Ne change rien d'autre
que ce fichier.

Dans le diff, vérifie ce que renvoie la fonction pour 1 et pour 2 : en français, le pluriel commence à 2, donc "1 photo" mais "2 photos". Beaucoup de conditions simples avec if trébuchent sur ces nombres.

Dans l'éditeur ci-dessous, tu actives ou non le debounce et tu comptes les questions envoyées au faux serveur : tape "coffre" avec le debounce et sans, puis compare le compteur.

À retenir : le timonier attend que le vent se stabilise, et le capitaine ne croit pas à "ça devrait marcher", il compte les lignes du journal du serveur.

Code de cette leçon : App.jsx
// Recherche avec debounce : combien de questions partent vers le serveur ?
// Le serveur est simulé : il attend 600 ms et filtre les photos selon la légende.
import { useEffect, useRef, useState } from 'react';

const photos = [
  {
    id: 'coucher-plage',
    src: 'https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600',
    alt: 'Vagues sur une plage de sable au coucher du soleil',
    caption: 'Ici, nous avons enterré le coffre',
  },
  {
    id: 'vagues-ciel',
    src: 'https://images.unsplash.com/photo-1505118380757-91f5f5632de0?w=600',
    alt: 'Vagues turquoise sur une plage blanche vues du ciel',
    caption: 'La baie vue du nid-de-pie',
  },
  {
    id: 'voilier-nuit',
    src: 'https://images.unsplash.com/photo-1534447677768-be436bb09401?w=600',
    alt: 'Petit voilier sur une mer calme sous un ciel étoilé',
    caption: 'Quart de nuit',
  },
  {
    id: 'palmiers',
    src: 'https://images.unsplash.com/photo-1519046904884-53103b34b206?w=600',
    alt: 'Palmiers et parasol de paille sur une plage blanche',
    caption: 'Île de la carte',
  },
  {
    id: 'sentier',
    src: 'https://images.unsplash.com/photo-1500530855697-b586d89ba3ee?w=600',
    alt: 'Chemin entre des rochers rouges menant vers une montagne',
    caption: 'Sentier vers la cachette',
  },
  {
    id: 'recif',
    src: 'https://images.unsplash.com/photo-1544551763-46a013bb70d5?w=600',
    alt: 'Plongeur au milieu d’un banc de poissons jaunes près d’un récif',
    caption: 'Plongée près du récif',
  },
];

function fakeServer(query) {
  return new Promise((resolve) => {
    setTimeout(() => {
      const phrase = query.trim().toLocaleLowerCase('fr');
      resolve(
        photos.filter((photo) =>
          photo.caption.toLocaleLowerCase('fr').includes(phrase),
        ),
      );
    }, 600);
  });
}

export default function App() {
  const [debounce, setDebounce] = useState(true);
  const [requests, setRequests] = useState([]);
  const [results, setResults] = useState(photos);
  const timer = useRef(null);

  const send = async (value) => {
    setRequests((prev) => [...prev, value.trim() || '(phrase vide)']);
    const found = await fakeServer(value);
    setResults(found);
  };

  const handleChange = (value) => {
    if (!debounce) {
      send(value);
      return;
    }
    // Chaque lettre annule le compte à rebours précédent et en lance un nouveau
    if (timer.current) clearTimeout(timer.current);
    timer.current = setTimeout(() => send(value), 300);
  };

  // Nettoyage : le compte à rebours ne survit pas à la disparition du composant
  useEffect(() => {
    return () => {
      if (timer.current) clearTimeout(timer.current);
    };
  }, []);

  return (
    <div className="min-h-screen bg-slate-100 p-4 text-slate-900">
      <h1 className="mb-3 text-2xl font-bold">Treasure Gallery</h1>

      <label className="mb-2 flex items-center gap-2 text-sm">
        <input
          type="checkbox"
          checked={debounce}
          onChange={(event) => setDebounce(event.target.checked)}
        />
        Debounce 300 ms
      </label>

      <input
        type="search"
        onChange={(event) => handleChange(event.target.value)}
        placeholder="Cherche dans les légendes..."
        aria-label="Chercher dans les légendes des photos"
        className="mb-3 w-full rounded border border-slate-300 bg-white px-3 py-2"
      />

      <div className="mb-3 rounded bg-white p-3 text-sm">
        <div className="mb-1 flex items-center justify-between">
          <span className="font-semibold">Questions au serveur : {requests.length}</span>
          <button
            type="button"
            onClick={() => setRequests([])}
            className="rounded bg-slate-200 px-2 py-1 text-xs"
          >
            Remettre le compteur à zéro
          </button>
        </div>
        <ol className="list-decimal pl-5 text-slate-600">
          {requests.map((phrase, index) => (
            <li key={index}>{phrase}</li>
          ))}
        </ol>
      </div>

      {results.length === 0 ? (
        <p className="py-8 text-center text-slate-600">
          Aucune photo n’a cette légende.
        </p>
      ) : (
        <ul className="grid grid-cols-2 gap-1 sm:grid-cols-3">
          {results.map((photo) => (
            <li key={photo.id} className="relative aspect-square bg-slate-800">
              <img
                src={photo.src}
                alt={photo.alt}
                className="absolute inset-0 h-full w-full object-cover"
              />
              <span className="absolute inset-x-0 bottom-0 bg-black/60 px-2 py-1 text-xs text-white">
                {photo.caption}
              </span>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. Qu'est-ce que le debouncing dans un champ de recherche ?

  2. 2. Après la saisie du mot « coffre », le terminal de npm run dev affiche six lignes : GET /gallery?q=c, ?q=co et ainsi de suite jusqu'à ?q=coffre. Que manque-t-il le plus probablement dans handleChange ?

Voici 2 des 5 questions de cette leçon. Réponds aux autres dans le jeu.

Tâches pratiques dans le jeu

  • Tri vertical

    Ordonne les lignes de la fonction handleChange avec debounce (de haut en bas) :

  • Clique dans l'ordre

    Clique sur les fragments dans l'ordre pour lire le paramètre q de l'adresse de la page :

  1. QuestionQuiz : Debouncing
  2. Remets dans l'ordreTri : Le debounce dans la fonction de gestion d'événement
  3. QuestionQuiz : Six lignes dans le terminal
  4. Clique dans l'ordreClic : La phrase de l'adresse
  5. QuestionQuiz : key sur Suspense
  6. QuestionQuiz : Filtrer dans le navigateur
  7. QuestionQuiz : useMemo et useCallback

Articles utiles