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
# PUBLIC_ prefix required for client-side access via import.meta.env
PUBLIC_ALGOLIA_APP_ID=56TZE3L6C6
PUBLIC_ALGOLIA_SEARCH_API_KEY=9e8bd7effb738f05bd107640cea03013
ALGOLIA_ADMIN_API_KEY=963f4a990dfe892ad6362b4c1c518912
PUBLIC_ALGOLIA_INDEX_NAME=amn_docs_dev

Notes :

• PUBLIC_ALGOLIA_APP_ID, PUBLIC_ALGOLIA_SEARCH_API_KEY, PUBLIC_ALGOLIA_INDEX_NAME : Le préfixe PUBLIC_ est requis pour exposer ces variables au code côté client via import.meta.env selon la documentation Astro. DocSearch a besoin de ces credentials côté client.
• ALGOLIA_ADMIN_API_KEY : Clé d’administration (pour l’indexation, à garder secrète, pas de préfixe PUBLIC_)
• Référence : https://docs.astro.build/en/guides/environment-variables/

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

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

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

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

// Configuration avancée DocSearch
// Les credentials sont accessibles via import.meta.env avec le préfixe PUBLIC_
// selon la documentation Astro : https://docs.astro.build/en/guides/environment-variables/
export default {
  // Credentials depuis les variables d'environnement (accessibles côté client)
  appId: import.meta.env.PUBLIC_ALGOLIA_APP_ID || 'PMZUYBQDAK',
  apiKey: import.meta.env.PUBLIC_ALGOLIA_SEARCH_API_KEY || '24b09689d5b4223813d9b8e48563c8f6',
  indexName: import.meta.env.PUBLIC_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
          // All DocSearch options are now in src/config/docsearch.ts
          clientOptionsModule: './src/config/docsearch.ts',
        }),
      ],
    }),
  ],
});

Note importante : Selon la documentation Starlight, quand clientOptionsModule est utilisé, toutes les options doivent être dans le fichier de module. Les options inline dans astro.config.mjs sont ignorées.

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.

---

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.