Intégration d'Algolia DocSearch dans Starlight SSR

1. Description de la Configuration

Afin d’associer le rendu dynamiquement sécurisé (Astro SSR + Better Auth src/middleware.ts) avec la recherche plein texte Starlight, le projet utilise l’intégration officielle @astrojs/starlight-docsearch.

---

2. Étapes de Configuration

A. Paquet requis

pnpm --filter amn-astro add @astrojs/starlight-docsearch

B. Configuration des variables d’environnement

Ajoutez les variables suivantes dans votre fichier .env :

# Algolia DocSearch Configuration
ALGOLIA_APP_ID=56TZE3L6C6
ALGOLIA_SEARCH_API_KEY=9e8bd7effb738f05bd107640cea03013
ALGOLIA_ADMIN_API_KEY=963f4a990dfe892ad6362b4c1c518912
ALGOLIA_INDEX_NAME=amn_docs_dev

Notes :

• ALGOLIA_SEARCH_API_KEY : Clé de recherche publique (utilisez-la uniquement côté client)
• ALGOLIA_ADMIN_API_KEY : Clé d’administration (pour l’indexation, à garder secrète)
• ALGOLIA_INDEX_NAME : Nom de l’index Algolia (sans espaces)

C. Configuration avancée avec fichier séparé

Pour une configuration avancée (transformItems, searchParameters, etc.), nous utilisons un fichier de configuration séparé.

1. Créer le fichier apps/web/src/config/docsearch.ts :

import type { DocSearchClientOptions } from '@astrojs/starlight-docsearch';

export default {
  // Credentials depuis les variables d'environnement
  // Fallback values are Algolia's public test credentials
  // They allow search to work even if env vars are incorrect
  appId: process.env.ALGOLIA_APP_ID || 'PMZUYBQDAK',
  apiKey: process.env.ALGOLIA_SEARCH_API_KEY || '24b09689d5b4223813d9b8e48563c8f6',
  indexName: process.env.ALGOLIA_INDEX_NAME || 'docsearch',

  // Transformation des résultats pour améliorer l'affichage
  // Note: Pour l'instant, retourne les items tels quels
  // Les transformations personnalisées nécessitent une gestion de type soigneuse
  transformItems(items) {
    return items;
  },

  // Paramètres de recherche optimisés
  searchParameters: {
    hitsPerPage: 8,
    // Récupérer uniquement les attributs nécessaires
    attributesToRetrieve: [
      'hierarchy.lvl0',
      'hierarchy.lvl1',
      'hierarchy.lvl2',
      'hierarchy.lvl3',
      'content',
      'type',
      'url',
    ],
    // Activer les snippets sur le contenu (10 mots par défaut)
    attributesToSnippet: ['content:10'],
    // Texte de fin de snippet personnalisé
    snippetEllipsisText: '...',
  },

  // Configuration de l'UI
  maxResultsPerGroup: 5,
  disableUserPersonalization: false,
  insights: true, // Activer pour analytics
} satisfies DocSearchClientOptions;

2. Mettre à jour astro.config.mjs :

import starlight from '@astrojs/starlight';
import starlightDocSearch from '@astrojs/starlight-docsearch';

export default defineConfig({
  integrations: [
    starlight({
      plugins: [
        starlightDocSearch({
          // Use separate config file for advanced options like transformItems()
          // All DocSearch options are now in src/config/docsearch.ts
          clientOptionsModule: './src/config/docsearch.ts',
        }),
      ],
    }),
  ],
});

Note sur les fallbacks : Les valeurs par défaut dans docsearch.ts (PMZUYBQDAK, 24b09689d5b4223813d9b8e48563c8f6, docsearch) sont les credentials de test publics d’Algolia. Elles permettent à la recherche de fonctionner même si les variables d’environnement ne sont pas correctement configurées, mais sur un index de test public.

D. Personnalisation de transformItems()

La fonction transformItems() permet de modifier les résultats de recherche avant affichage. Pour l’utiliser :

transformItems(items) {
  return items.map((item) => ({
    ...item,
    // Ajouter ou modifier des propriétés
    // Exemple: nettoyer les titres, filtrer, trier, etc.
  }));
}

Attention : Les transformations personnalisées nécessitent une gestion soigneuse des types TypeScript. Assurez-vous que le type de retour correspond à DocSearchHit[].

---

3. Procédure de Test et Validation

1. Validation TypeScript :

   task typecheck

2. Build Web :

   task build:web

3. Test Local Wrangler Dev :

   task dev:wrangler

   • Accéder à http://localhost:8787/gettingstarted/34-starlight-algolia-docsearch-integration/.
   • Cliquer sur le bouton Search ou utiliser le raccourci Ctrl+K.
   • Vérifier que le modal Algolia s’affiche correctement.