createVtexCommerceLoaders() não registra vtex/loaders/legacy/suggestions — causa sugestões silenciosas em migrações

Problema

Durante a migração Fresh → TanStack Start da Miess, a barra de busca não exibia sugestões/autocomplete. Não havia nenhum erro visível — o invoke simplesmente resolvia null.

Causa raiz

useAutocomplete.ts (padrão gerado nas migrações) chama:

const suggestions = invoke.vtex.loaders.legacy.suggestions

Isso resolve a chave vtex/loaders/legacy/suggestions no runtime. Porém createVtexCommerceLoaders() não registra essa chave — ela só registra vtex/loaders/intelligentSearch/suggestions.ts.

A função legacySuggestions existe e está corretamente exportada em @decocms/apps/vtex/loaders/legacy.ts:

export {
  legacySuggestions as suggestions,
  // ...
}

Mas não é incluída no objeto retornado por createVtexCommerceLoaders().

Workaround aplicado na Miess

Registrar manualmente em commerce-loaders.ts:

import { legacySuggestions } from '@decocms/apps/vtex/loaders/legacy'

export const COMMERCE_LOADERS = {
  // ...
  'vtex/loaders/legacy/suggestions.ts': (props: any) =>
    legacySuggestions({ query: props?.query, count: props?.count }),
  'vtex/loaders/legacy/suggestions': (props: any) =>
    legacySuggestions({ query: props?.query, count: props?.count }),
}

---

Como evitar em futuras migrações

Existem algumas opções:

Opção A — Incluir todos os loaders legacy em createVtexCommerceLoaders()

Registrar vtex/loaders/legacy/suggestions (e demais loaders legacy que possam estar faltando) dentro de createVtexCommerceLoaders(), da mesma forma que os loaders IS já estão incluídos.

Prós: zero configuração para quem migra
Contras: aumenta levemente o bundle, pode conflitar com overrides customizados

Opção B — Checagem em build/dev de loaders invocados mas não registrados

Quando o compilador gera o runtime.ts / invoke, checar se toda chave de loader que aparece em invoke.X.Y.Z está de fato registrada em COMMERCE_LOADERS. Emitir aviso (ou erro) em build time.

Prós: detecta o problema sem precisar rodar a app
Contras: requer análise estática do código do site

Opção C — Fallback runtime com log de aviso

Se uma chave de loader não for encontrada em COMMERCE_LOADERS, emitir um console.warn descritivo ao invés de retornar null silenciosamente:

[deco] invoke: loader key 'vtex/loaders/legacy/suggestions' not registered in COMMERCE_LOADERS.
  → Did you forget to add it? See https://...

Prós: fácil de implementar, não quebra nada
Contras: só aparece em runtime, não em build

---

Contexto

• Projeto afetado: Miess (TanStack Start)
• @decocms/apps versão: ver package.json do projeto
• O mesmo padrão provavelmente afeta qualquer site migrado do Fresh que use o legacy autocomplete ao invés do IS autocomplete

Start with createVtexCommerceLoaders() and compare its registrations with the exports in @decocms/apps/vtex/loaders/legacy.ts. Trace the vtex/loaders/legacy/suggestions lookup from useAutocomplete.ts and inspect the workaround in commerce-loaders.ts. Decide which proposed behavior the issue should implement, then verify that legacy suggestions resolve without silently returning null.