Page Contract

Contrato canônico de templates e composição de páginas na Corvex.

Esta página é o contrato canônico para Templates e composição de páginas.

Uma página na loja é uma instância de um template type com uma lista ordenada de sections e seus settings.

---

Template types (sistema)

type	Uso público
index	Home
product	Detalhe do produto
collection	Listagem de coleção/categoria
cart	Carrinho
search	Busca
blog	Listagem de blog
article	Artigo
page	Página institucional custom (PAGE:{handle} no runtime)

Templates index, product, collection, cart, search MUST existir no Theme (Theme Contract).

---

MUST — arquivo templates/{type}.json

{
  "name": "Página inicial",
  "type": "index",
  "sections": {
    "hero": {
      "type": "hero",
      "settings": { "title": "Bem-vindo" }
    },
    "featured": {
      "type": "featured-products",
      "settings": { "limit": 4 }
    }
  },
  "order": ["hero", "featured"]
}

Campo	Quem exige
Arquivo templates/{type}.json	O validador, para os cinco tipos obrigatórios
sections	O formato que o starter e o discover leem
order	O discover usa o array quando existe. Sem ele, a ordem vira a das chaves do objeto. O validador não reprova a ausência
name	Texto do starter. O validador não exige

---

MUST — instância de section

{
  "type": "hero",
  "settings": { },
  "blocks": { },
  "block_order": []
}

Campo	Obrigatório
type	REQUIRED — section type registrado no tema
settings	OPTIONAL
blocks	OPTIONAL
block_order	OPTIONAL — REQUIRED se blocks presente

type MUST corresponder a um ID em theme.json → sections.

---

Defaults vs instância da loja

Artefato	Onde	Função
templates/*.json	Pacote do tema	Defaults ao instalar tema
Draft da loja	Persistido pelo Editor	Composição atual do merchant
Published	Revisão publicada	Loja ao vivo

O merchant edita a instância; o arquivo no tema define defaults.

---

Layout groups (global)

Sections em layoutGroups (header/footer) são injetadas antes/depois do conteúdo do template, não listadas em cada templates/*.json.

---

URLs públicas (visitante)

Path	Template
/	index
/products/:handle, /produtos/:handle	product
/collections/:handle, /colecoes/:handle	collection
/cart	cart
/search, /busca	search
/blogs/:blog	blog — o mapper monta essa URL. O parser de rota publicada deste repositório não trata blogs
/blogs/:blog/articles/:article	article — mesma ressalva
/page/:handle	page — não aparece em publishedStorefrontRoute.js

---

Contexto de página

Cada template type expõe objetos de página via Theme SDK (usePage, useCorvexContext). Ver Data Contract.

---

Restrições

• MUST NOT usar pages/*.json no lugar de templates/*.json.
• O validador não pede templates/checkout.json. Checkout não é um template do tema.

---

Veja também

• Theme Contract
• Data Contract
• Publish Contract