Regras de escopo

Quem pode buscar dados, mutar estado e declarar settings em cada camada do tema.

Template / Page
    ↓
Section
    ↓
Block
    ↓
Snippet

Camada	Page context	Query (fetch)	Mutation	Settings
Template	✅	✅	✅	✅
Section	✅	✅ (defineSectionData)	limitado	✅
Block	✅ usePage	❌ catálogo	✅ useCorvexCart	✅
Snippet	via props	❌ catálogo	✅ useCorvexCart	❌

Veja o Mapa de dados → schema.data completo (reviews, recommendations, cart, coupons, …).

Section declara dados — componente renderiza

export const schema = defineSection({
  name: 'Lista de produtos',
  settings: [
    { type: 'collection', id: 'collection', label: 'Coleção' },
    { type: 'range', id: 'limit', label: 'Quantidade', min: 2, max: 24, default: 8 },
  ],
});

export const data = defineSectionData(async ({ storefront, settings }) => ({
  products: await storefront.products.list({
    collection: settings.collection,
    first: settings.limit,
  }),
}));

export default function ProductList({ settings, data }) {
  return data.products.nodes.map((product) => (
    <ProductCard key={product.id} product={product} />
  ));
}

A runtime Corvex (preview/loja publicada):

1. Coleta as sections do layout da página
2. Executa defineSectionData e/ou resolve schema.data
3. Deduplica loaders com mesmas settings
4. Executa em paralelo
5. Injeta data nas sections que declararam dependência

No canvas do Editor, o preview usa o mesmo contrato de props (settings, data).

Blocks e snippets não listam o catálogo

useCorvexCart vale em section, block e snippet. Ele lê o provider do carrinho. Listagem de produtos, categorias e reviews fica na section (defineSectionData ou schema.data).

// ✅ Block recebe product da section pai
function ProductCard({ product }) {
  return (
    <>
      <img src={product.featuredImage?.url} alt={product.title} />
      <h3>{product.title}</h3>
      <span>{product.price.formatted}</span>
    </>
  );
}

// ❌ Block buscando API
async function ProductCard() {
  const products = await fetch('/api/...');
}

Carrinho = Action, não Query

import { useCorvexCart } from '@corvex/theme-sdk';

const { items, total, addItem } = useCorvexCart();

addItem(product, 1);

Separe na documentação:

• Queries — catálogo, menus, páginas
• Actions — cart, checkout, customer

Veja Cart actions.