Spécification Technique - Intégration Algolia DocSearch dans Starlight

Spécification Technique : Intégration Algolia DocSearch dans Starlight

1. Contexte & Problématique

Dans le cadre de l’architecture hybride Astro SSR sur Cloudflare Workers :

1. Les documentations Starlight (/docs/ et /gettingstarted/) sont configurées avec prerender: false pour permettre au middleware Astro (src/middleware.ts) d’intercepter les requêtes HTTP et de contrôler l’accès via Better Auth.
2. Le moteur de recherche par défaut de Starlight (Pagefind) nécessite la génération statique de fichiers HTML au build (prerender: true). En mode SSR (prerender: false), Pagefind ne trouve pas de fichiers HTML statiques dans dist/client, ce qui rend la recherche inaccessible ou vide (No results).
3. Pour conserver le contrôle d’accès dynamique par middleware tout en bénéficiant d’une recherche performante, Starlight recommande l’intégration officielle d’Algolia DocSearch via le plugin @astrojs/starlight-docsearch.

---

2. Solution Retenue (DOC → SPEC)

L’intégration du plugin officiel @astrojs/starlight-docsearch permet de remplacer l’UI du modal de recherche natif par le modal d’Algolia DocSearch sans modifier le comportement des routes SSR ni compromettre la sécurité Better Auth.

---

3. Matrice des Modifications

A. Paquets Nouveaux

• @astrojs/starlight-docsearch (ajouté aux dépendances de apps/web)

B. Fichiers de Configuration

1. apps/web/astro.config.mjs

   • Importation du plugin starlightDocSearch depuis @astrojs/starlight-docsearch.
   • Ajout de starlightDocSearch({ appId, apiKey, indexName }) dans le tableau plugins de l’intégration starlight().
   • Nettoyage des stubs/overrides de recherche locaux non standards.

2. apps/web/.env et apps/web/.env.example

   • Ajout des variables ALGOLIA_APP_ID, ALGOLIA_SEARCH_API_KEY, et ALGOLIA_INDEX_NAME.

---

4. Protocole de Validation & Tests (TEST → INTÉG)

1. Contrôle de Type TypeScript : task typecheck (0 erreurs exigées).
2. Validation du Build Web : task build:web (Compilation des bundles sans avertissements critiques).
3. Test d’Exécution Locale : task dev:wrangler (Vérification de l’ouverture du modal Algolia sur http://localhost:8787).