@searchmindai/searchmind-search

Plugin oficial de Searchmind AI Search para VTEX FastStore v2.

Agrega un overlay de búsqueda con IA semántica, filtros por facetas, scroll infinito y analytics GA4 sobre cualquier store FastStore v2.

Requisitos

• VTEX FastStore v2 (@faststore/cli ≥ 4.x)
• Node.js ≥ 18
• Yarn 1.x o npm ≥ 8
• API key de Searchmind

Instalación

1. Instalar el paquete

Desde la raíz de la tienda:

npm install @searchmindai/searchmind-search
# o con yarn
yarn add @searchmindai/searchmind-search

2. Configurar FastStore

En discovery.config.js, agregar dentro de experimental la clave transpilePackages y luego el array plugins:

module.exports = {
  // ...resto de la config...

  experimental: {
    nodeVersion: 18,
    transpilePackages: ['@searchmindai/searchmind-search'],
  },

  plugins: ['@searchmindai/searchmind-search'],
}

Importante: transpilePackages es obligatorio. Sin él, FastStore no transpila el TSX del plugin y el build falla.

plugins genera automáticamente la ruta de API /api/plugins/searchmind que actúa como proxy seguro hacia la API de Searchmind.

3. Configurar la API key

En vtex.env:

SEARCHMIND_API_KEY=tu_api_key_aqui

La key nunca se expone al browser — el proxy la usa server-side.

4. Ejecutar el setup

Desde la raíz de la tienda:

npx searchmind-setup

Este comando detecta automáticamente la raíz del proyecto y:

• Crea src/Layout.tsx con el componente SearchmindOverlay
• Crea scripts/prebuild-layout.js (parche del Layout de FastStore)
• Actualiza los scripts predev y build en package.json

5. Instalar dependencias y correr la tienda

yarn install
yarn dev

Cómo funciona

FastStore regenera .faststore/ en cada ejecución a partir de @faststore/core. Para integrar el overlay sin modificar archivos regenerados, el plugin usa el siguiente mecanismo:

src/Layout.tsx          ← fuente de verdad (versionada en el repo de la tienda)
      │
scripts/prebuild-layout.js
      │
      ├─→ node_modules/@faststore/core/src/Layout.tsx   (parche previo al dev/build)
      └─→ .faststore/src/Layout.tsx                     (si ya existe)

Los scripts predev y build garantizan que el parche se aplique antes de que FastStore genere la build.

Scripts agregados a package.json

El setup agrega los siguientes scripts automáticamente:

| Script | Descripción | |---|---| | predev | Aplica el parche del Layout antes de faststore dev | | build | Aplica el parche del Layout antes de faststore build |

Importante para CI/CD: el script postinstall no debe apuntar a prebuild-layout.js. En Docker, los archivos del proyecto no están disponibles durante yarn install. El build script es suficiente para producción.

Estructura del overlay

El componente SearchmindOverlay se inicializa en el Layout de la tienda y:

1. Intercepta clicks/focus en [data-fs-search-input] (el input de búsqueda de FastStore)
2. Obtiene la configuración de facetas desde /api/plugins/searchmind?type=settings
3. Al abrirse, muestra un modal fullscreen con:
   • Input de búsqueda con debounce (350ms)
   • Grid de productos con skeleton loading
   • Sidebar de filtros por facetas (configurados en el panel de Searchmind)
   • Chips de filtros activos
   • Scroll infinito
4. Enter navega a /s?q=<query>
5. Todas las llamadas a la API van a través del proxy — la API key nunca sale del servidor

Props de SearchmindOverlay

| Prop | Tipo | Default | Descripción | |---|---|---|---| | apiUrl | string | /api/plugins/searchmind | URL del proxy de búsqueda | | triggerSelector | string | [data-fs-search-input] | Selector CSS del input de búsqueda | | locale | string | en-US | Locale para formato de precios | | currency | string | USD | Código de moneda ISO 4217 | | searchPath | string | /s | Ruta de la página de resultados |

Los valores de locale y currency se leen automáticamente desde discovery.config.js (session.locale y session.currency.code).

Variables de entorno

| Variable | Descripción | |---|---| | SEARCHMIND_API_KEY | API key del store (requerida, solo servidor) | | SEARCHMIND_API_URL | URL base de la API (opcional, default: https://api.searchmindai.com) |

Actualizar el plugin

# Con npm
npm update @searchmindai/searchmind-search

# Con yarn
yarn upgrade @searchmindai/searchmind-search

Troubleshooting

El overlay no aparece

Verificar que prebuild-layout.js corrió correctamente:

node scripts/prebuild-layout.js

Debe imprimir @faststore/core/src/Layout.tsx parcheado.

Error en producción: Cannot find module '/app/scripts/prebuild-layout.js'

El postinstall no puede referenciar scripts/prebuild-layout.js — en Docker, esos archivos no están disponibles durante yarn install. Verificar que package.json no tenga postinstall apuntando a ese script.

Error de build: SyntaxError o JSX transform failed en el plugin

Verificar que discovery.config.js tenga transpilePackages configurado:

experimental: {
  transpilePackages: ['@searchmindai/searchmind-search'],
},

Sin esta config, Next.js no transpila el TSX del plugin.

Los cambios del plugin no se reflejan después de actualizar

Verificar que node_modules/@searchmindai/searchmind-search tiene la versión esperada:

npm list @searchmindai/searchmind-search

Facetas no aparecen

Los filtros se configuran en el panel de administración de Searchmind y se obtienen via /api/plugins/searchmind?type=settings. Verificar que SEARCHMIND_API_KEY esté correctamente configurada en vtex.env.