La première objection que j’entends, c’est qu’un site statique ne peut pas avoir de recherche puisqu’il n’y a pas de serveur à interroger. C’est faux. Vous pouvez construire un index de recherche au moment de la génération du site et le publier comme un simple fichier, puis le parcourir entièrement dans le navigateur. Pour quelques milliers de documents au plus, c’est assez rapide pour que les utilisateurs croient à un backend.
Pourquoi la recherche côté client fonctionne
L’astuce est de déplacer le travail au moment du build. Pendant que mon générateur parcourt déjà chaque page pour produire le HTML, il est trivial d’y collecter aussi le titre, l’URL et le texte de chacune dans une liste. Cette liste devient un fichier JSON. Le navigateur le télécharge une fois, construit un index en mémoire, et chaque frappe ensuite est instantanée car rien ne quitte l’appareil. Pas de base de données, pas d’API, aucun coût par requête.
Construisez l’index au moment de la génération
Pendant le build, je retire les balises HTML de chaque page et j’ajoute un petit enregistrement à un tableau. Gardez le texte du corps réduit ; vous n’avez pas besoin de chaque mot, et un index plus léger se télécharge plus vite. Voici l’essentiel :
const index = pages.map(page => ({
title: page.title,
url: page.url,
excerpt: page.excerpt,
body: page.text.slice(0, 2000)
}));
fs.writeFileSync('dist/search-index.json', JSON.stringify(index));Écrire ce fichier n’est qu’une étape de plus dans le même pipeline qui produit vos pages, donc cela s’insère naturellement dans un build que vous lancez peut-être déjà via le CI/CD avec GitHub Actions. L’index est publié à côté de votre HTML sur le même réseau de périphérie.
Choisissez une bibliothèque, ou écrivez la version bête
Pour les petits sites, vous pouvez vraiment écrire votre propre comparateur en une douzaine de lignes. Mettez tout en minuscules, découpez la requête en mots, et notez les documents selon le nombre de mots qu’ils contiennent. Ça marche. Mais dès que vous voulez la tolérance aux fautes, la correspondance par préfixe ou un classement par pertinence, prenez une bibliothèque. J’aime Fuse.js pour la correspondance approximative et MiniSearch quand je veux un vrai score plein texte. Les deux sont minuscules et tournent dans le navigateur sans étape de build.
import MiniSearch from 'minisearch';
const res = await fetch('/search-index.json');
const docs = await res.json();
const mini = new MiniSearch({
fields: ['title', 'body'],
storeFields: ['title', 'url', 'excerpt']
});
mini.addAll(docs);
const results = mini.search('cloudflare deploy', { fuzzy: 0.2 });Reliez-le au champ de saisie
Branchez un écouteur sur votre champ de recherche, mais ne lancez pas une recherche à chaque frappe. Temporisez de 150 millisecondes environ, sinon une personne qui tape vite déclenche une douzaine de recherches pour un seul mot. À chaque événement temporisé, lancez la requête, prenez les meilleurs résultats, et affichez-les comme une liste de liens. Montrez le titre et l’extrait pour que les gens sachent quel résultat ils veulent avant de cliquer.
- Temporisez la saisie pour chercher sur une pause, pas à chaque lettre.
- Limitez aux huit ou dix premiers résultats ; personne ne fait défiler un menu de recherche.
- Surlignez le terme correspondant dans le résultat pour que la pertinence saute aux yeux.
- Gérez explicitement l’état vide et l’état sans résultat.
Chargez l’index paresseusement
Ne téléchargez pas l’index de recherche au chargement de la page. La plupart des visiteurs ne cherchent jamais, donc payer ce coût d’avance est du gaspillage. Je récupère le JSON la première fois que quelqu’un place le curseur dans le champ de recherche, je le mets en cache dans une variable, et je le réutilise. La première recherche a un minuscule délai pendant l’arrivée du fichier, toutes les suivantes sont instantanées, et ceux qui ne cherchent jamais ne paient pas un octet. Cela garde votre chargement initial léger, ce qui compte pour les mêmes raisons qui m’obsèdent dans l’optimisation des images pour le web.
Quand s’arrêter et passer à un service
La recherche côté client a un plafond. Au-delà d’environ dix mille documents, l’index devient assez gros pour que le télécharger et l’analyser fasse mal, surtout sur téléphone. À cette échelle, je passe à un service de recherche hébergé qui expose une API. Mais honnêtement, la plupart des blogs et des sites de doc n’approchent jamais cette limite. Construisez l’index, publiez le JSON, cherchez dans le navigateur, et vous obtenez une fonctionnalité qui semble coûteuse pour presque rien et zéro serveur à maintenir.
