Skip to content
AMN Docs

[Nom de l'Intégration API Pagefind]

[Nom de l'Intégration API Pagefind]

Documentation technique

Type de ressource : API JavaScript Pagefind (Recherche programmatique)
Fichier source : src/components/ui/SearchBar.astro ou composant associé
Statut : [Actif / Déprécié / En développement]
Slice : [Numéro de la tranche verticale]
Version : 1.0

1. Vue d’ensemble (DOC)

1.1. Description

[Description concise du rôle de cette intégration API dans l’architecture de recherche du site]

1.2. Objectif

  • [Objectif principal : ex. fournir une recherche custom avec contrôle total sur l’UI et le comportement]
  • [Bénéfice par rapport à Pagefind UI natif : ex. personnalisation complète, intégration design system]

1.3. Périmètre concerné1/3

Couverture Statut
Vitrine [✅/❌]
Blog [✅/❌]
Portfolio [✅/❌]
Documentation [✅/❌]
Tout [✅/❌]

1.3. Périmètre concerné2/3

Type d’API Statut
Pagefind JS API [✅/❌]
Pagefind UI custom [✅/❌]
Les deux [✅/❌]

1.3. Périmètre concerné3/3

Emplacement Statut
Header global [✅/❌]
Page dédiée [✅/❌]
Modal [✅/❌]
Sidebar [✅/❌]

2. Architecture et flux (DOC)

2.1. Diagramme de flux

[Utilisateur]
     │  (saisie dans la barre de recherche)
     ▼
[Composant SearchBar (Astro)]
     │  • Import dynamique de Pagefind
     │  • Initialisation de l'index
     │  • Debounce sur l'input
     ▼
[Pagefind JS API]
     │  • Chargement de l'index chunké
     │  • Recherche côté client
     │  • Application des filtres
     ▼
[Résultats]
     │  • Extraction des métadonnées
     │  • Distinction visuelle par type
     │  • Pagination / Limitation
     ▼
[Interface custom]
     │  • Rendu des résultats
     │  • Badges (Doc, Blog, Portfolio, Page)
     ▼
[Utilisateur]
     │  (clic sur un résultat)
     ▼
[Navigation vers la page]

2.2. Composants impliqués

Composant Rôle Fichier
SearchBar.astro Interface de recherche globale src/components/ui/SearchBar.astro
SearchResults.astro Affichage des résultats src/components/ui/SearchResults.astro
SearchFilters.astro Filtres par type de contenu src/components/ui/SearchFilters.astro
Pagefind JS API Bibliothèque JS de recherche pagefind (npm)
Index Pagefind Index chunké généré au build dist/_pagefind/

3. Implémentation de l’API Pagefind (CODE)

3.1. Import et initialisation

src/components/ui/SearchBar.astro
<div class="search-container" data-pagefind-ignore="all">
  <input
    type="search"
    id="search-input"
    placeholder="Rechercher..."
    class="search-input"
    autocomplete="off"
    aria-label="Rechercher dans le site"
  />


  <div id="search-results" role="region" aria-label="Résultats de recherche" aria-live="polite">
    <!-- Résultats injectés dynamiquement -->
  </div>
</div>


<script>
  // Import dynamique de Pagefind (lazy loading)
  let pagefind: any = null;


  async function initPagefind() {
    if (pagefind) return;


    // Import dynamique pour éviter de charger Pagefind au chargement initial
    // @ts-ignore
    pagefind = await import('/pagefind/pagefind.js');
    await pagefind.init();
  }


  // Initialisation au premier focus
  const searchInput = document.getElementById('search-input');
  searchInput?.addEventListener('focus', initPagefind);
</script>

3.2. Recherche avec filtres

// Fonction de recherche avec filtres
async function search(query: string, filters?: { type?: string }) {
  if (!pagefind) await initPagefind();


  const results = await pagefind.search(query, {
    filter: (result) => {
      if (filters?.type) {
        return result.meta?.type === filters.type;
      }
      return true;
    },
  });


  return results;
}

4. Contrats d’Entrée/Sortie (SPEC)

4.1. Inputs (Requête de recherche)

Paramètre Type Validation
query string Non vide
filters object Filtres valides

4.2. Outputs (Résultats)

Élément Type Description
results array Liste des résultats
meta object Métadonnées

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario Description Résultat attendu
Initialisation Premier focus Pagefind chargé
Recherche Terme valide Résultats retournés
Filtres Filtre appliqué Résultats filtrés

5.2. Tests d’intégration

Scénario Dépendances Description Résultat attendu
Flux complet Index + API Recherche → Résultats Résultats affichés

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant Type Rôle Méthode d’intégration
SearchBar L2 Interface Composant Astro
Index Build Données Pagefind CLI

6.2. Points d’attention

  • L’import doit être dynamique (lazy loading)
  • Le debounce doit être configuré
  • Les filtres doivent être cohérents avec les métadonnées

6.3. Vérification de cohérence

  • L’API est initialisée correctement
  • Les résultats sont pertinents
  • Les filtres fonctionnent
  • Les tests E2E passent

7. Sécurité

7.1. Mécanismes de sécurité

  • ✅ Pas d’exposition de données sensibles
  • ✅ Validation des entrées

7.2. Règles de sécurité

  • ✅ Sanitization des requêtes
  • ✅ Limite de résultats

8. Performance et limites

8.1. Limites

Limite Valeur
Taille de l’index ~10 MB
Temps de chargement ~1s

8.2. Optimisations

  • ✅ Lazy loading
  • ✅ Debounce
  • ✅ Pagination

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme Cause probable Solution
Pagefind non chargé Import échoué Vérifier le chemin
Résultats vides Index vide Vérifier le build

9.2. Commandes de debug

Terminal window
# Build local
npm run build


# Preview
npm run preview

10. Bonnes pratiques

10.1. Architecture

  • ✅ Lazy loading de Pagefind
  • ✅ Debounce sur l’input
  • ✅ Filtres cohérents

10.2. Code

  • ✅ TypeScript strict
  • ✅ Gestion des erreurs
  • ✅ Accessibilité

11. Évolutions et roadmap

11.1. Améliorations planifiées

  • [Évolution 1]
  • [Évolution 2]

11.2. Limitations connues

  • ❌ [Limitation 1]
  • ❌ [Limitation 2]

12. Ressources liées

13. Historique des modifications

Date Version Description Auteur
YYYY-MM-DD 1.0 Création initiale [Nom]
Switch to normal mode

Contents

Built with StarlightPowered by Cloudflare