Intégration d'Algolia DocSearch dans Starlight SSR

Guide d'implémentation et de test du système de recherche Algolia DocSearch pour les sites Starlight en mode 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’environnement1/2

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

B. Configuration des variables d’environnement2/2

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é1/4

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 :

C. Configuration avancée avec fichier séparé2/4

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;

C. Configuration avancée avec fichier séparé3/4

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',
        }),
      ],
    }),
  ],
});

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

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()1/2

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.
  }));
}

D. Personnalisation de transformItems()2/2

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

Validation TypeScript :
Terminal window
```
task typecheck
```
Build Web :
Terminal window
```
task build:web
```
Test Local Wrangler Dev :
Terminal window
```
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.