Corvex — Temas

Todos os exemplos assumem que você está dentro da pasta do seu tema (cd minha-loja).

`corvex init`

Cria um tema Corvex a partir do scaffold oficial.

corvex init . --name "Minha Loja" --slug minha-loja

O scaffold inclui package.json com "dev": "corvex dev".

`corvex dev`

Servidor oficial de desenvolvimento do tema (preview local + hot reload).

npm run dev
# ou
corvex dev .
corvex dev . --port 5180 --open
corvex dev . --host 0.0.0.0
corvex dev . --live-reload full-page
corvex dev . --ignore "**/*.md" --only "sections/**"
corvex auth && corvex link && corvex dev . --store

Flag	Default	Efeito
`--port`	`5173`	Porta HTTP (se ocupada, tenta a próxima; com `--port` fixo falha se ocupada)
`--host`	`127.0.0.1`	Bind local. Rede só com host explícito (`0.0.0.0`)
`--open`	off	Abre o navegador na URL do preview
`--live-reload`	`hot-reload`	`hot-reload` (CSS hot + remount JSX), `full-page` ou `off`
`--ignore`, `-x`	—	Glob ignorado no watch (repetível)
`--only`, `-o`	—	Restringe o watch a globs (repetível)
`--store`, `-s`	off (mock)	Modo conectado: API pública da loja (exige `corvex auth`). Sem valor usa `corvex link` / `CORVEX_DEV_STORE_ID`
`--verbose`	off	Loga eventos de watch/HMR
`--notify`	—	Atualiza o arquivo (mtime) após cada build ok

O que faz

Detecta a raiz do tema (theme.json) e valida o essencial
Compila com o mesmo pipeline de corvex build (buildThemeBundleV2)
Serve o tema real (templates, layout groups, seções, blocos, snippets, settings, assets)
Padrão: mock determinístico em /api/corvex-api (sem auth, sem loja real)
Com --store: preview com catálogo da loja vinculada (via Theme SDK); imprime URL do Editor quando há vínculo
CSS: hot swap; JSX/estrutura: remonta o preview; schema/templates/theme.json: reload completo (modo hot-reload)
Overlay de erros (compile / validate / runtime)
Ctrl+C encerra watchers e o servidor

Rotas de preview (contrato de vitrine): /, /products/:handle, /collections/:handle, /search, /cart, /blogs/..., /pages/:handle. Não faz: sync bidirecional editor↔arquivos no dev, preview compartilhável por túnel, overwrite automático. Use corvex pull / corvex sync com modo explícito. Sem --store não exige corvex auth, corvex link nem corvex sync.

`corvex auth` · `corvex link`

corvex auth
corvex link
corvex whoami

Autenticação e vínculo com loja — pré-requisito para sync e instalação no Editor.

`corvex validate`

Valida manifest, schemas, templates obrigatórios e bundle.

corvex validate .

Verifica:

theme.json (manifestVersion: 2, slug, sections, templates)
config/settings.schema.json
templates/index, product, collection, cart, search
Cada section em theme.json tem section.jsx + schema.json
Grava schema.identity.json (name atual + nomes já vistos). Rename de name é permitido. Commite o lockfile. Ver identidade.

O bundle não é pré-requisito. Dá para validar antes do build. Falta de screenshots/desktop e screenshots/mobile gera aviso e não reprova. A linha de sucesso é Tema válido: {slug}@{version}.

`corvex check`

Theme Check — análise ampliada (reutiliza o validate + regras de SDK, JSX, a11y estática e performance).

corvex check .
corvex check . --json
corvex check . --list

Detalhes, regras e CI: Theme Check.

`corvex mcp`

Servidor MCP oficial (stdio) para agentes: contratos, validate, check, build e Dev Server local.

corvex mcp
corvex mcp doctor
corvex mcp setup --cursor

Detalhes e segurança: MCP Server.

`corvex build`

Compila sections, snippets e assets do tema.

corvex build .

Saída confirmada no starter:

.corvex/theme.js — bundle do tema
.corvex/locales.json — quando o tema tem locales/

A mensagem é Bundle compilado: seguida do caminho de .corvex/theme.js. Anexa no bundle (não importe esses JSON no JSX nem declare propriedade estática no componente):

schema.json de cada section → schema e defaults do inspector (CLI ≥ 2.3.3)
blocks.json de cada section → lista de blocks do inspector (CLI ≥ 2.3.4)
schema.json de cada block → schema do block (CLI ≥ 2.3.5)

Use @corvex/theme-cli 2.3.5+. Sem o attach do schema do block, o item no inspector aparece sem configurações.

`corvex sync`

Build + publica versão PRIVATE na loja vinculada. Por padrão, em terminal interativo, a CLI pergunta o que deve ser atualizado na loja. Use flags para pular o menu ou forçar um modo específico.

corvex sync .
corvex sync . --open              # abre o Editor após sync
corvex sync . --keep-content      # só código — preserva editor
corvex sync . --with-templates    # código + templates do pacote local
corvex sync . --full              # instalação nova (reset)
corvex sync . -y                  # sem prompt (modo "só código")

O que cada modo faz

Modo	Flag	Código (JS/CSS/seções)	Templates / conteúdo do editor
Só código	`--keep-content` / `--content code`	Atualiza bundle na instalação atual	Preservado — textos, imagens, ordem de sections
Código + templates	`--with-templates` / `--content templates`	Atualiza bundle	Reaplica `default-templates.json` do tema local
Instalação completa	`--full` / `--content full`	Nova instalação na loja	Templates e settings padrão do pacote

Quando usar cada modo

Só código (recomendado no dia a dia de dev):

Você alterou CSS, JS ou markup de uma section
O merchant já personalizou textos, imagens e layout no Editor
Você quer ver o código novo sem apagar o trabalho do painel

corvex sync . --keep-content --open

Código + templates:

Você mudou a estrutura padrão das páginas no repositório (templates/*.json)
Quer que a loja receba esses layouts padrão (sobrescreve o rascunho das páginas no Editor)

Instalação completa:

Primeira instalação ou reset total
Quer descartar personalizações e voltar ao estado padrão do tema

Comportamento técnico

corvex build — compila o bundle
POST /stores/storefront/catalog/themes/publish — nova versão PRIVATE no catálogo
Na loja:
- Só código / templates: PATCH .../themes/:storeThemeId/version na instalação existente (lastStoreThemeId em corvex.theme.json)
- Full: POST .../themes/install — nova instalação
Se modo templates: reaplica draftDocument de cada template a partir do pacote local
Salva metadados em corvex.theme.json

Flags de conteúdo

Flag	Alias	Modo
`--keep-content`	`--code-only`	`code`
`--with-templates`	`--reset-templates`	`templates`
`--full`	`--reset-content`	`full`
`--content <modo>`	—	`code`, `templates` ou `full`
`-y` / `--yes`	—	Pula o menu; usa modo só código

`corvex pull`

Baixa arquivos do tema para a pasta local. Há dois modos:

Modo	Comando	Origem dos dados
Loja (padrão)	`corvex pull .`	Instalação atual na loja (inclui edições do Editor)
Catálogo	`corvex pull . --version 1.0.130`	Source archive da versão publicada no marketplace

Pull da loja (padrão)

Inverso do sync. Útil quando o merchant personalizou a loja no Editor e você quer o mesmo código + templates + settings na pasta local.

corvex pull .
corvex pull . --force           # sobrescreve arquivos locais
corvex pull . --zip              # gera .cvex-theme.zip após o download
corvex pull . --out ./backup     # salva em outra pasta
corvex pull . --no-refresh       # só baixa o que já está no servidor

Inclui:

Código-fonte do tema (sections, layout, schemas)
config/settings.data.json — settings atuais da loja
templates/*.json — composição das páginas (rascunho do Editor)

Pré-requisito: a loja precisa ter source archive no catálogo (rode corvex sync pelo menos uma vez). Sem isso, o servidor não monta o snapshot para download.

Pull de versão do catálogo (`--version`)

Baixa o código-fonte publicado em uma versão específica do tema (o zip enviado no corvex publish / corvex sync), sem templates/settings editados no Editor depois.

corvex pull . --version 1.0.130
corvex pull . --version v1.1.0 --force
corvex pull . --version <themeVersionId> --slug meu-tema

Flag	Descrição
`--version`	Semver (`1.0.130`, `v1.1.0`) ou UUID da `themeVersionId`
`--slug`	Slug do tema no catálogo (opcional se `theme.json` ou `corvex.theme.json` já têm o slug)
`--force`	Sobrescreve arquivos locais existentes
`--zip`	Gera `.cvex-theme.zip` após o download
`--out`	Pasta de destino

O slug é resolvido nesta ordem: --slug → corvex.theme.json → catalogSlug → theme.json → slug. Não exige loja vinculada — só autenticação (corvex auth). A versão precisa ter sido publicada com source archive (comportamento padrão do publish/sync desde v2.2+).

Fluxos típicos

# Estado atual da loja (com edições do Editor)
corvex auth
corvex link . --store <uuid-da-loja>
corvex pull . --force

# Voltar ao código de uma versão publicada
corvex auth
corvex pull . --version 1.0.130 --force

corvex build
corvex pack .

`corvex pack`

Gera ZIP distribuível do tema.

corvex pack .
corvex pack . --out dist/meu-tema-1.0.0.zip

`corvex publish`

Publica uma versão do tema no catálogo Corvex (código do tema — não é o “Publicar” do merchant no Editor).

corvex publish . --visibility PRIVATE
corvex publish . --update --visibility PUBLIC --bump minor

Flags comuns

Flag	Valores	Descrição
`--visibility`	`PRIVATE`, `PUBLIC`	Visibilidade no catálogo
`--update`	—	Nova versão do mesmo `slug`
`--bump`	`patch`, `minor`, `major`	Incremento de versão
`--install`	—	Instala na loja vinculada após publish

Resposta

{
  "definition": { "slug": "meu-tema" },
  "version": { "id": "uuid-theme-version", "version": "1.0.0" }
}

Guarde version.id (themeVersionId) para instalação.

`corvex skills`

Skills de tema empacotadas na CLI. Não baixam da rede. A versão instalada é a compatível com manifestVersion, não necessariamente a maior que existir no futuro.

corvex skills install .
corvex skills update . --yes
corvex skills status .
corvex skills list .
corvex skills doctor .
corvex skills disable .

install não substitui arquivo editado por você e não apaga skill de terceiro. update sem --yes não grava. --force só tem efeito junto com --yes. Guia: Agent Skills.

`corvex --help`

Lista comandos e opções atualizadas da sua instalação.

Separação importante

Ação	Ferramenta	O que publica
Código do tema	`corvex publish`	Versão no catálogo
Layout da loja	Editor → Publicar	Conteúdo do merchant

Ver Publish Contract.

Começar

Conceitos-chave

APIs e referências

Guias

Otimizar

Ferramentas

Marketplace

Storefront Components

Comandos da CLI

`corvex init`

`corvex dev`

`corvex auth` · `corvex link`

`corvex validate`

`corvex check`

`corvex mcp`

`corvex build`

`corvex sync`

O que cada modo faz

Quando usar cada modo

Comportamento técnico

Flags de conteúdo

`corvex pull`

Pull da loja (padrão)

Pull de versão do catálogo (`--version`)

Fluxos típicos

`corvex pack`

`corvex publish`

Flags comuns

Resposta

`corvex skills`

`corvex --help`

Separação importante

​corvex init

​corvex dev

​corvex auth · corvex link

​corvex validate

​corvex check

​corvex mcp

​corvex build

​corvex sync

​O que cada modo faz

​Quando usar cada modo

​Comportamento técnico

​Flags de conteúdo

​corvex pull

​Pull da loja (padrão)

​Pull de versão do catálogo (--version)

​Fluxos típicos

​corvex pack

​corvex publish

​Flags comuns

​Resposta

​corvex skills

​corvex --help

​Separação importante

`corvex init`

`corvex dev`

`corvex auth` · `corvex link`

`corvex validate`

`corvex check`

`corvex mcp`

`corvex build`

`corvex sync`

O que cada modo faz

Quando usar cada modo

Comportamento técnico

Flags de conteúdo

`corvex pull`

Pull da loja (padrão)

Pull de versão do catálogo (`--version`)

Fluxos típicos

`corvex pack`

`corvex publish`

Flags comuns

Resposta

`corvex skills`

`corvex --help`

Separação importante