Saltar a contenido

ADR-0002 · Algolia e InstantSearch como motor de búsqueda, en vez de la búsqueda de Medusa

  • Estado: aceptado
  • Decisores: no registrado en el repositorio
  • Fecha de la decisión: no registrada. Primera implementación en el commit 35cd3d8 ("menu de navegacion + algolia instantSearch").

Contexto y problema

La tienda necesita búsqueda con autocompletado, facetas y respuesta inmediata sobre un catálogo de retail. El endpoint de listado de productos de Medusa resuelve filtros por categoría y colección, pero no da búsqueda por texto con tipado incremental ni sugerencias de consulta, y cada tecla contra el backend es carga que no queremos.

Opciones consideradas

  1. Algolia con react-instantsearch (elegida).
  2. La búsqueda propia de Medusa sobre /store/products.
  3. Un motor autoalojado (Meilisearch, Typesense).

No hay registro de la comparación; la opción 3 no dejó rastro en el repositorio.

Decisión

Algolia es el motor de búsqueda del storefront. Se usan dos índices (NEXT_PUBLIC_ALGOLIA_PRODUCT_INDEX y ..._SUGGESTIONS_INDEX) y dos clientes distintos: src/lib/algolia.ts con el paquete completo para operaciones server-side, y src/lib/search-client.ts con algoliasearch/lite para los componentes de InstantSearch en el navegador. La indexación no la hace este repo: los scripts scripts/populate-suggestions.js y los populate-*.js de la raíz solo pueblan las sugerencias.

El alcance creció más allá del buscador: las grillas de producto de la home también se resuelven contra Algolia (src/lib/algolia-products.ts).

Consecuencias

Positivas

  • Búsqueda instantánea con facetas y sugerencias sin carga sobre Medusa.
  • react-instantsearch-nextjs permite renderizar resultados del lado del servidor en el App Router.

Negativas / deuda asumida

  • La home depende de la búsqueda. Si el índice está vacío o desactualizado, no solo falla el buscador: las grillas de la home quedan vacías.
  • Dos enfoques de búsqueda conviviendo (InstantSearch client-side y consultas server-side), documentado en integraciones/algolia.md.
  • El catálogo queda duplicado fuera de Medusa: todo desfase de indexación se ve como precios o stock incorrectos en la vitrina.
  • Costo por operación de un SaaS, proporcional al tráfico.
  • La configuración por variables de entorno ya causó una falla vigente: el cliente del navegador lee una variable que no existe (falla 2 del runbook).