Instalações de Tema

Uma instalação de tema é uma instância de tema com escopo de loja — uma cópia de trabalho com seus próprios arquivos, configurações e estado. Sua loja tem uma instalação produtiva (ativa na loja) e pode ter uma segunda que serve como rascunho ou experimento.

Duas instalações por vez

Uma loja pode ter no máximo duas instalações em qualquer momento. Se você atingiu o limite e quer criar uma nova, exclua uma instalação não-produtiva existente para liberar o espaço.

O Nuvemshop CLI permite que você gerencie o ciclo de vida completo das instalações pelo terminal:

criar → baixar → enviar/monitorar → fork (opcional) → publicar → excluir

theme pull --theme-id <id> salva o ID da instalação em .nuvem, para que os comandos subsequentes a utilizem como alvo sem precisar de --theme-id a cada vez.

información

Antes de usar esses comandos, execute theme authorize para conectar o CLI à sua loja. Veja Fork workflow para instruções de configuração.

Somente tema Ipanema

As instalações de tema e o fluxo de fork estão disponíveis apenas para o tema Ipanema, que ainda está em fase de rollout e pode não estar disponível para todas as lojas. Em temas legados com FTP aberto, use o Fluxo FTP (legado) .

Listar

Liste todas as instalações de tema na sua loja:

nuvemshop theme list

A saída mostra o ID, título, versão do tema, se é produtiva (ativa), se foi feito fork e se está arquivada em cada instalação. A coluna archived indica instalações arquivadas — instalações antigas que foram guardadas e não estão mais em uso ativo. Use --json para saída legível por máquina:

nuvemshop theme list --json

Opções

Opção	Descrição
--json	Exibe a saída em JSON em vez de tabela
--token <token>	Token de autenticação (uso em CI )
-v	Ativa a saída detalhada

Criar

Crie uma nova instalação a partir de um código de tema:

nuvemshop theme create --base-theme ipanema --title "Meu Tema"

Isso cria uma instalação nova com base nos arquivos e configurações padrão do tema base especificado. Atualmente, o único valor suportado para --base-theme é ipanema. No futuro, mais temas serão adicionados ao catálogo.

Opções

Opção	Descrição
--base-theme <name>	Obrigatório. Tema base para criar a instalação (atualmente, apenas ipanema)
--title <name>	Obrigatório. Um nome legível para a instalação
--json	Exibe a saída em JSON
--token <token>	Token de autenticação (uso em CI )
-v	Ativa a saída detalhada

Selecionando a instalação ativa

Não há um comando checkout separado. O CLI vincula um diretório a uma instalação quando você executa:

nuvemshop theme pull --theme-id ID_DO_TEMA

Após um pull bem-sucedido, o ID da instalação é salvo em .nuvem. Comandos subsequentes como theme push, theme watch e theme publish/fork/clone/delete/preview utilizam automaticamente essa instalação quando --theme-id é omitido.

Para verificar qual instalação o diretório atual está vinculado:

nuvemshop theme current

Clonar

Crie uma cópia idêntica de uma instalação existente:

nuvemshop theme clone

Ao contrário do criar (que parte dos padrões do tema base), clonar duplica uma instalação existente — incluindo qualquer modificação de arquivos, alterações de configurações e personalizações que você fez. Útil quando você quer experimentar mudanças sem afetar o trabalho atual.

Opções

Opção	Descrição
--theme-id <id>	A instalação a ser clonada (padrão: a instalação vinculada a este diretório)
--title <title>	Título da nova instalação (padrão: <origem> (copy))
--published	Usa o tema publicado da loja em vez de --theme-id ou .nuvem
--json	Exibe a saída em JSON
--token <token>	Token de autenticação (uso em CI )
-y	Pula os prompts de confirmação
-v	Ativa a saída detalhada

Fork

Em breve

O fork de instalações está chegando em breve. Estamos finalizando uma forma de manter as instalações forkadas sempre atualizadas com o tema base, e logo o recurso estará disponível. Por enquanto, executar nuvemshop theme fork retorna um aviso de que o fork ainda não está liberado.

Enquanto isso, você já pode usar todo o restante do fluxo de tema (criar, baixar, enviar, monitorar e publicar instalações) e personalizar sua loja pela camada de personalização (templates/, custom/ e config/settings_data.json).

Faça fork de uma instalação para desbloquear acesso completo aos arquivos:

nuvemshop theme fork

Por que o fork existe

Uma instalação do tema Ipanema separa o código do tema das personalizações. O código do tema é o núcleo — os layouts, templates de seção, blocos, estilos e scripts que definem a aparência e o comportamento da loja. As personalizações são as partes que variam por loja — quais seções aparecem em cada página, suas configurações e quaisquer arquivos customizados.

A árvore de arquivos de uma instalação baixada tem esta estrutura:

meu-tema/
├── blocks/            ← Código do tema: templates de bloco (.tpl)
├── config/
│   ├── settings_schema.json   ← Código do tema: define as configurações disponíveis
│   └── settings_data.json     ← Personalização: valores salvos pelo lojista
├── layouts/           ← Código do tema: estrutura HTML principal
├── locales/           ← Código do tema: arquivos de tradução
├── sections/          ← Código do tema: templates de seção (.tpl)
├── snippets/          ← Código do tema: partials compartilhados (.tpl)
├── static/            ← Código do tema: CSS, JS, assets
├── templates/         ← Personalização: templates de página (.json)
└── custom/            ← Personalização: arquivos adicionados pelo desenvolvedor

Por padrão, uma instalação sem fork protege o código do tema e permite apenas modificar a camada de personalização:

Permitido sem fork	O que contém
templates/	Templates de página (.json) — definem quais seções aparecem em cada página, sua ordem e configurações
custom/	Arquivos customizados adicionados pelo desenvolvedor
config/settings_data.json	Os valores de configuração salvos pelo lojista

Isso significa que você pode reorganizar seções em uma página, alterar configurações ou adicionar arquivos customizados — mas não pode tocar nos templates .tpl, estilos, scripts ou qualquer outro arquivo do núcleo.

Fazer fork remove essa restrição. Uma vez feito o fork, o CLI permite que você envie qualquer arquivo do tema — incluindo layouts, seções, blocos, snippets, assets estáticos e o schema de configurações.

Quando fazer fork

Não faça fork se você só precisa:

• Mudar quais seções aparecem em uma página (editar templates/*.json)
• Ajustar configurações de seção (editar templates/*.json ou config/settings_data.json)
• Adicionar arquivos customizados (adicionar arquivos em custom/)

Esse é o caminho mais seguro — sua instalação permanece compatível com futuras atualizações do tema.

Faça fork quando precisar:

• Editar a lógica HTML/Twig de uma seção (sections/*.tpl)
• Modificar templates de bloco (blocks/*.tpl)
• Alterar o layout principal (layouts/layout.tpl)
• Atualizar estilos ou scripts (static/)
• Adicionar ou modificar traduções (locales/)
• Alterar o schema de configurações (config/settings_schema.json)

Opções

Opção	Descrição
--theme-id <id>	A instalação a ser forkada (padrão: a instalação vinculada a este diretório)
--published	Usa o tema publicado da loja em vez de --theme-id ou .nuvem
--json	Exibe a saída em JSON
--token <token>	Token de autenticação (uso em CI )
-y	Pula os prompts de confirmação
-v	Ativa a saída detalhada

peligro

Fazer fork é uma operação sem volta na própria instalação. Uma instalação forkada não volta a ser sem fork no lugar — mas você pode usar theme unfork para gerar um novo rascunho sem fork a partir dela, mantendo suas personalizações. Se você fizer fork de uma instalação já forkada, o CLI trata isso como uma operação sem efeito.

información

Apenas temas baseados em seções (como o Ipanema) podem ser forkados. A API rejeitará solicitações de fork para temas não seccionáveis.

Unfork

Reverta o fork de uma instalação, gerando um novo rascunho sem fork:

nuvemshop theme unfork

Ao contrário do fork, o unfork não modifica a instalação de origem. Ele cria uma nova instalação (rascunho) que mantém seus templates e configurações, mas descarta o código do tema forkado — reativando as atualizações automáticas do tema pela Nuvemshop/Tiendanube. A instalação de origem permanece intacta.

Use o unfork quando você fez fork de uma instalação mas quer voltar a receber atualizações automáticas do tema base, sem perder suas personalizações (templates/, custom/ e config/settings_data.json).

Opções

Opção	Descrição
--theme-id <id>	A instalação a ser desforkada (padrão: a instalação vinculada a este diretório)
--title <title>	Título da nova instalação (padrão: <origem> (unforked))
--published	Usa o tema publicado da loja em vez de --theme-id ou .nuvem
--json	Exibe a saída em JSON
--token <token>	Token de autenticação (uso em CI )
-y	Pula os prompts de confirmação
-v	Ativa a saída detalhada

Atualizar

Atualize uma instalação para uma versão mais nova do seu tema base, gerando um novo rascunho:

nuvemshop theme update

O update não modifica a instalação de origem. Ele cria uma nova instalação (rascunho) já na versão escolhida, mantendo suas personalizações. A instalação atual continua intacta, então você pode pré-visualizar o rascunho e só publicar quando estiver confiante.

Ao final, o CLI informa o ID da nova instalação. Execute theme pull --theme-id <novo_id> para baixar os arquivos atualizados.

Lembre do limite de duas instalações

Como o update cria uma nova instalação, sua loja precisa ter uma vaga livre. Se já existem duas, exclua a instalação não-produtiva antes.

Escolhendo a versão

As versões disponíveis dependem da instalação, então o CLI as consulta na API antes de qualquer coisa:

• Em uma instalação sem fork, o alvo é um major (por exemplo, 2) — ela sempre recebe a última release daquele major.
• Em uma instalação forkada, o alvo é uma versão exata (por exemplo, 2.3.1).

Sem --to, o CLI mostra a lista e pede que você escolha. Com --to, o valor é validado contra essa mesma lista e o comando falha indicando as opções válidas caso não exista. Se a instalação já estiver na versão mais recente, o CLI apenas informa que não há nada a atualizar.

Simulando antes (--dry-run)

Antes de executar, veja o que a atualização faria:

nuvemshop theme update --dry-run

O relatório mostra a versão de origem, a versão de destino e a lista de arquivos em conflito — arquivos que você modificou e que serão substituídos pelas versões novas do tema. Esse mesmo relatório aparece no prompt de confirmação de uma atualização real, então você nunca confirma às cegas.

Em ambiente não interativo (CI), --dry-run sem --to funciona como descoberta: em vez de exigir um alvo, ele lista a versão atual e as versões disponíveis.

Em CI

Fora de um terminal interativo não há como escolher da lista, então --to é obrigatório e -y dispensa a confirmação:

# Descobrir as versões disponíveis
nuvemshop theme update --dry-run --json

# Atualizar para uma delas
nuvemshop theme update --to 2 -y --json

Opções

Opção	Descrição
--theme-id <id>	A instalação a ser atualizada (padrão: a instalação vinculada a este diretório)
--to <version>	Versão de destino. Instalação forkada aceita a versão exata (2.3.1); sem fork, o major (2). Omita para escolher da lista
--title <title>	Título da nova instalação (padrão: <origem> (v<versão>))
--dry-run	Apenas relata o que a atualização faria, sem alterar nada
--published	Usa o tema publicado da loja em vez de --theme-id ou .nuvem
--json	Exibe a saída em JSON
--token <token>	Token de autenticação (uso em CI )
-y	Pula os prompts de confirmação
-v	Ativa a saída detalhada

información

Atualizações do tema base chegam automaticamente a instalações sem fork. O theme update é o caminho para instalações forkadas, que deixam de receber essas atualizações, e para quando você quer controlar o momento exato da mudança de versão.

Publicar

Torne uma instalação o tema produtivo (ativo) na sua loja:

nuvemshop theme publish

Publicar torna a instalação visível para todos os visitantes. A instalação anteriormente produtiva é rebaixada — ela ainda existe, mas não está mais ativa.

Opções

Opção	Descrição
--theme-id <id>	A instalação a ser publicada (padrão: a instalação vinculada a este diretório)
--json	Exibe a saída em JSON
--token <token>	Token de autenticação (uso em CI )
-y	Pula os prompts de confirmação
-v	Ativa a saída detalhada

peligro

Publicar substitui o tema ativo atual. Sempre teste suas mudanças com uma pré-visualização antes de publicar.

URL de Pré-visualização

Obtenha uma URL de pré-visualização de uma instalação sem torná-la ativa:

nuvemshop theme preview

Isso gera uma URL no formato:

https://sualojanuvemshop.com.br?theme_installation_id=ID_DA_INSTALACAO

Abra no navegador para ver como a instalação fica na loja. A pré-visualização é visível apenas para você — não afeta o que os visitantes veem.

Opções

Opção	Descrição
--theme-id <id>	A instalação a ser pré-visualizada (padrão: a instalação vinculada a este diretório)
--published	Usa o tema publicado da loja em vez de --theme-id ou .nuvem
--token <token>	Token de autenticação (uso em CI )

Performance

Execute um relatório de performance com Lighthouse na versão atual do tema:

nuvemshop theme performance

O comando roda uma auditoria Lighthouse contra a URL de pré-visualização da loja para a instalação em uso e imprime um relatório por dispositivo — mobile e desktop por padrão — com a pontuação geral de performance e as principais métricas (First Contentful Paint, Speed Index, Largest Contentful Paint, Total Blocking Time, Cumulative Layout Shift e Time to Interactive).

A auditoria usa o Chromium empacotado com o CLI (sem configuração extra), roda em modo headless e pode levar um ou dois minutos.

información

O comando precisa da store_url salva em .nuvem. Se ela não estiver presente, execute theme authorize novamente para salvar a URL da sua loja.

Escolha o fator de forma com --device, inclua as recomendações do relatório com --detailed ou obtenha uma saída legível por máquina com --json:

nuvemshop theme performance --device mobile
nuvemshop theme performance --detailed
nuvemshop theme performance --json

Com --detailed, o relatório também lista as mudanças recomendadas do Lighthouse (oportunidades e diagnósticos que falharam, do maior ao menor impacto, com exemplos concretos). Com --json, os resultados ficam organizados por dispositivo em results.mobile e results.desktop.

Opções

Opção	Descrição
--theme-id <id>	A instalação a ser analisada (padrão: a instalação vinculada a este diretório)
--published	Usa o tema publicado da loja em vez de --theme-id ou .nuvem
--device <both\|mobile\|desktop>	Qual fator de forma auditar (padrão: both)
--detailed	Inclui as mudanças recomendadas do relatório do Lighthouse
--json	Exibe a saída em JSON
--token <token>	Token de autenticação (uso em CI )

Excluir

Exclua uma instalação de tema:

nuvemshop theme delete

Opções

Opção	Descrição
--theme-id <id>	A instalação a ser excluída (padrão: a instalação vinculada a este diretório)
--json	Exibe a saída em JSON
--token <token>	Token de autenticação (uso em CI )
-y	Pula os prompts de confirmação
-v	Ativa a saída detalhada

peligro

Excluir uma instalação é permanente e não pode ser desfeito. Você não pode excluir a instalação produtiva atual.

Referência rápida

Comando	Descrição
theme list	Lista todas as instalações na loja
theme create	Cria uma nova instalação a partir de um código de tema
theme current	Mostra a instalação vinculada a este diretório
theme clone	Duplica uma instalação existente
theme fork	Desbloqueia acesso completo aos arquivos (sem volta)
theme unfork	Cria um novo rascunho sem fork, reativando atualizações
theme update	Cria um novo rascunho em uma versão mais nova do tema base
theme publish	Torna uma instalação ativa na loja
theme preview	Gera um link de pré-visualização sem publicar
theme performance	Roda um relatório de performance (Lighthouse) do tema
theme delete	Remove permanentemente uma instalação