Erros comuns (temas e agências)

Guia rápido para evitar bugs recorrentes ao consumir a Storefront Data API.

1. Imagem de categoria/coleção

❌ Errado

// category.image é um objeto Image após o SDK — não use como src direto
<img src={category.image} alt={category.title} />

O browser recebe [object Object] e a imagem quebra.

✅ Correto

<img
  src={category.imageUrl || category.image?.url || ''}
  alt={category.image?.altText || category.title}
/>

Origem	Formato
Backend `GET /categories`	`image: "https://cdn.../foto.png"` (string)
SDK `mapCategorySummary`	`image: { url, altText, ... }` + `imageUrl: string`

Produtos seguem o mesmo padrão: use product.featuredImage?.url ou getProductImage(product).

2. Coleção ≠ entidade separada

Você pensa	Realidade no Corvex
API `/collections`	`GET /categories`
`storefront.collections.*`	alias de `storefront.categories.*`
URL `/collections/verao`	categoria com `slug: verao`

Filtrar produtos por coleção:

storefront.products.list({ collection: 'uuid-da-categoria' });
// backend: ?categoryId=uuid

3. `useCorvexData` e formato do retorno

O hook legado retorna Connection<T> com nodes. Sempre normalize:

const products = data?.nodes ?? [];
// ou
import { unwrapCorvexNodes } from '@corvex/theme-sdk';
const products = unwrapCorvexNodes(data);

Não assuma que data é array.

4. `limit` vs `first`

Contexto	Parâmetro
`storefront.products.list()`	`first`
`useCorvexData('products', …)`	`limit` (mapeado para `first`)
`storefront.categories.list()`	`first`
`useCorvexData('collections', …)`	`limit`

5. Produtos por categoria + `status`

❌ Evite

storefront.products.list({
  collection: categoryId,
  status: 'PUBLISHED', // costuma retornar 0 itens
});

✅ Prefira

storefront.products.list({
  collection: categoryId,
  inStock: true, // se quiser só com estoque
  // omita status na listagem geral
});

Detalhes: products.list — Status e categoria.

6. Picker `collection` salva UUID

No inspector, type: "collection" persiste o UUID da categoria, não o handle:

{ "collection": "72a0c0d1-9c0d-41a0-a23c-64099ea04bfd" }

Passe esse valor direto para collection / categoryId na query de produtos.

7. Contexto de página vs fetch extra

Em template product, a plataforma já injeta o produto:

const { product } = usePage('product');

❌ Redundante na PDP

const product = await storefront.products.getByHandle(params.handle);

Em template collection, use page.collection e page.products — não busque de novo sem motivo.

8. Blocks e snippets não fazem fetch

Só sections (via defineSectionData ou useCorvexData no componente da section) buscam catálogo.

// ✅ snippet recebe dados da section pai
function CollectionCard({ category }) {
  return <img src={category.imageUrl} alt={category.title} />;
}

Ver Regras de escopo.

9. `available` vs `inStock`

Código legado usava available: true. A API pública espera:

inStock: true  // query ?inStock=true

10. Aliases de ordenação

O SDK aceita aliases comuns de ordenação e normaliza para o backend:

Setting / SDK	Backend
`BEST_SELLING`	`createdAt`
`TITLE`	`name`
`PRICE`	`price`

11. Preview no editor (URL)

Além de ?theme= e ?version=, o editor persiste estado de preview:

Param	Exemplo	Restaura
`page`	`page=product`	Template ativo no editor
`product`	`product=uuid-ou-handle`	Produto no preview PDP
`collection`	`collection=uuid`	Coleção no preview
`q`	`q=tenis`	Termo de busca
`carouselPage`	`carouselPage=2`	Página do carrossel (se section suportar)

Exemplo:

/?theme=...&version=...&page=home&carouselPage=1
/?theme=...&version=...&page=product&product=uuid-do-produto

Ver Contexto de página.

12. Preview responsivo no editor

O canvas do editor reduz a largura do container (390px mobile, 768px tablet), mas @media e window.matchMedia usam a janela do browser por padrão. O host emula o device quando você troca o ícone Desktop / Tablet / Mobile:

Reaplica regras CSS do tema como se a viewport tivesse a largura do device
Patcheia matchMedia para JS que usa breakpoints (ex.: menu mobile)

No tema: prefira category.image?.url e, se usar window.innerWidth / matchMedia, considere useEditorPreviewState ou CSS puro com @media. Recarregue o editor após atualizar o host. O preview em /preview e no celular real não precisam dessa emulação.

13. Editor — blocks e carrossel

Erros do canvas, não da Data API.

Sintoma	Causa provável
Tela branca ao remover bloco	`{children}` montado duas vezes no JSX
`removeChild` no console	O mesmo DOM duplicado ao excluir
`Cannot update … while rendering …`	`setState` dentro do updater de `useState`
Carrossel parado no editor	Bundle antigo. O modo inspecionar não troca a árvore: `useBuilderBlockEditLayout()` devolve sempre `false`
Inspector da section errado	Propriedade estática no componente. Apague, rode `corvex build` e `corvex sync`. Contrato da section

Nunca:

Renderizar {children} em dois lugares.
Usar SectionBlockCanvas na vitrine publicada.
Chamar um callback dentro de setPage((current) => { … return next }).

Guia: Runtime API.

14. Vazamento de CSS (tema para o builder)

No editor, tema e builder compartilham a mesma página. Se o tema grava cores em :root ou em document.documentElement, a UI do editor herda essas variáveis.

❌ Errado

/* assets/theme.css */
:root {
  --color-primary: #1570c3;
}

.container { max-width: 1200px; }

document.documentElement.style.setProperty('--color_primary', settings.color_primary);

✅ Correto

Defina variáveis só nas raízes do tema (layout, header, footer):

.my-theme-root,
.header-pro-root,
.qvx-footer-pro {
  --color-primary: var(--brand-primary);
}

.my-theme-root .container {
  max-width: 1200px;
}

Sintoma no builder	Causa
Botões Salvar/Publicar com cor da loja	`--color_primary` / `--brand-primary` no `:root`
Inspetor com tipografia do tema	`body`, `*` ou `button` sem escopo
Layout do inspetor quebrado	`.container` ou grid global sem prefixo

A plataforma aplica settings do painel Tema em .cx-theme-scope — o CSS do tema também deve ficar escopado. Guia completo: Escopo CSS — tema vs editor.

15. Canvas do builder branco

Sintoma

/preview e vitrine ok
Canvas do editor (/?store=…) branco, sem erro no console
Seções aparecem na árvore lateral

Causas

Causa	Correção
Overlay de portal (clone de layout com `100vh` + fundo)	Plataforma colapsa qualquer shell em fluxo; no tema, portalize só o overlay
CSS só no `ThemeLayout`	Plataforma aplica classes `theme-root` extraídas no `.cx-theme-scope`; declare `editorPreviewRootClasses` se o nome for atípico
Slideshow/hero altura 0	Regras `[data-corvex-editor-preview='true']` + `min-height`
Portal em `document.body`	`useThemePortalTarget()`
Pack desatualizado	`corvex build` + sync/publish

✅ Correto

{
  "editorPreviewRootClasses": ["my-theme-root", "my-theme-root--variant"]
}

[data-corvex-editor-preview='true'] .dm-slideshow:not(.dm-slideshow--preserve-ratio) {
  min-height: var(--dm-slideshow-height-mobile, 420px);
}

Guia completo: Compatibilidade iframe do editor

16. Vídeo com UUID no src

❌ Errado

// settings.heroVideo pode ser UUID da biblioteca — não é URL
<video src={settings.heroVideo} autoPlay muted playsInline />

O browser não reproduz UUID; o hero fica vazio ou quebra silenciosamente.

✅ Correto

import CorvexVideo from '@corvex/snippets/corvex-video';

<CorvexVideo
  value={settings.heroVideo}
  poster={settings.heroPoster || settings.heroImage}
  autoplay
  muted
  loop
  controls={false}
/>

Origem do valor	Formato em `settings`	Renderização
Biblioteca / Enviar	UUID (`a1b2…`)	Classificar → resolver HLS ou poster
URL (YouTube/Vimeo/MP4)	`https://…`	Embed ou `<video src>`

Guia completo: Biblioteca de vídeos · FAQ.

17. Carrossel de vídeos e loop HLS

❌ Errado — recriar HLS quando visibilidade muda

useEffect(() => {
  hls?.destroy();
  const hls = new Hls();
  hls.loadSource(src);
  if (shouldPlay) video.play();
}, [src, shouldPlay]); // marquee + IntersectionObserver → milhares de seg_*.mp4

Também evite:

playWhenVisible em faixa marquee com autoplay (observer instável com animação CSS)
video.src = manifest.m3u8 após erro fatal do Hls.js
Resolver UUID / fetch de /playback dentro do block em vez do snippet CorvexVideo

✅ Correto

// Snippet: setup HLS só quando src muda; play/pause em outro efeito
// Section marquee: playWhenVisible={false}
// Block: useCorvexVideoPlayback via CorvexVideo

Modo	`playWhenVisible`	Streams ativos
Hero único	opcional	1
Embla (1 slide)	sim — pause inativos	1
Marquee autoplay	false	vários (buffer baixo, sem recriar HLS)
Grid	false — play no clique	1

Guia completo: Carrossel de vídeos (Reels).

18. Grade de produtos — snippet vs blocos de catálogo

❌ Errado — misturar modelos na mesma expectativa

Editar blocos na seção Início (main) e esperar que o carrossel Vitrine de produtos (product-list + snippet) mude.
Repetir renderCatalogProductBlocks com blocks desatualizados no editor sem useSectionLiveBlocks().
Colocar type errado em blocks[id] (todos catalog-product-image) — sintoma: várias imagens, sem título/descrição.
order no template apontando para "main" sem objeto sections.main com blocks + block_order.

✅ Correto

Snippet: import ProductCard from '@corvex/snippets/product-card' — card fixo; customização via settings da section ou props do snippet. Ver Product Card.
Blocos de catálogo: section busca produtos; cada item da grade usa a mesma block_order; blocks leem produto via contexto. Ver Grade com blocos de catálogo.
Persistência: blocks e block_order (template e publicação). No editor, useSectionLiveBlocks() espelha os tipos ao vivo.
O tipo é a pasta blocks/{id}/. Se schema.json tiver type, use o mesmo id. name é o rótulo no editor e pode mudar.
No editor, monte {children} no primeiro card da grade — não em host oculto com clip/aria-hidden (seleção de bloco fica desalinhada).

​Erros comuns (temas e agências)

​1. Imagem de categoria/coleção

​❌ Errado

​✅ Correto

​2. Coleção ≠ entidade separada

​3. useCorvexData e formato do retorno

​4. limit vs first

​5. Produtos por categoria + status

​❌ Evite

​✅ Prefira

​6. Picker collection salva UUID

​7. Contexto de página vs fetch extra

​❌ Redundante na PDP

​8. Blocks e snippets não fazem fetch

​9. available vs inStock

​10. Aliases de ordenação

​11. Preview no editor (URL)

​12. Preview responsivo no editor

​13. Editor — blocks e carrossel

​14. Vazamento de CSS (tema para o builder)

​❌ Errado

​✅ Correto

​15. Canvas do builder branco

​Sintoma

​Causas

​✅ Correto

​16. Vídeo com UUID no src

​❌ Errado

​✅ Correto

​17. Carrossel de vídeos e loop HLS

​❌ Errado — recriar HLS quando visibilidade muda

​✅ Correto

​18. Grade de produtos — snippet vs blocos de catálogo

​❌ Errado — misturar modelos na mesma expectativa

​✅ Correto

​Checklist antes de publicar section

​Referências

Erros comuns (temas e agências)

1. Imagem de categoria/coleção

❌ Errado

✅ Correto

2. Coleção ≠ entidade separada

3. `useCorvexData` e formato do retorno

4. `limit` vs `first`

5. Produtos por categoria + `status`

❌ Evite

✅ Prefira

6. Picker `collection` salva UUID

7. Contexto de página vs fetch extra

❌ Redundante na PDP

8. Blocks e snippets não fazem fetch

9. `available` vs `inStock`

10. Aliases de ordenação

11. Preview no editor (URL)

12. Preview responsivo no editor

13. Editor — blocks e carrossel

14. Vazamento de CSS (tema para o builder)

❌ Errado

✅ Correto

15. Canvas do builder branco

Sintoma

Causas

✅ Correto

16. Vídeo com UUID no src

❌ Errado

✅ Correto

17. Carrossel de vídeos e loop HLS

❌ Errado — recriar HLS quando visibilidade muda

✅ Correto

18. Grade de produtos — snippet vs blocos de catálogo

❌ Errado — misturar modelos na mesma expectativa

✅ Correto

Checklist antes de publicar section

Referências