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
# 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

B. Configuration des variables d’environnement2/2

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

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 :

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

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;

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
          // 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 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

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.