@nuvler/cli

CLI oficial para criar, migrar, desenvolver, validar, compilar, empacotar e publicar temas Nuvler.

Requisitos e instalação

• Node.js ^20.19.0 ou >=22.12.0;
• npm;
• uma chave de conexão do painel Nuvler para preview e publicação.

Uso sem instalação global:

npx @nuvler/cli@latest --help
npx @nuvler/cli@latest theme templates

Instalação ou atualização global:

npm install --global @nuvler/cli@latest
nuvler --version

Projetos criados pela CLI instalam @nuvler/cli como devDependency e expõem os comandos mais usados por scripts npm. Assim, não é necessário instalar o CLI globalmente dentro do projeto.

Fluxo recomendado

nuvler theme create tema-raja --name "Tema Raja" --template starter
cd tema-raja
npm install
npx nuvler theme configure --key CHAVE_COPIADA_DO_PAINEL
npm run validate
npm run dev
npm run typecheck
npm run build
npm run pack
npm run publish

Não crie um .env para API, token ou tenant. A chave configura a API e a autenticação global; o projeto guarda somente a identificação não sensível do tenant em .nuvler/config.json, que é ignorado pelo Git.

Tutoriais para desenvolvedores

Tutorial 1 — Transformar um projeto React existente em tema Nuvler

Este fluxo recria a parte visual de um projeto React + TypeScript em uma nova pasta de tema. A V1 aceita projetos Vite e Next.js. O projeto original é usado somente para leitura: não execute o comando com o destino dentro da origem.

1. Instale ou atualize o CLI

node --version
npm install --global @nuvler/cli@latest
nuvler --version

Também é possível usar npx @nuvler/cli@latest no lugar da instalação global.

2. Execute a migração a partir da pasta que contém os projetos

cd /caminho/dos/projetos

nuvler theme migrate ./site-existente --output ./tema-nuvler

Com nome e identificador explícitos:

nuvler theme migrate ./site-existente --output ./tema-nuvler \
  --id tema-nuvler --name "Tema Nuvler"

O destino deve ser uma pasta nova ou vazia e deve ficar fora da origem. Por padrão, a CLI instala as dependências, valida o manifesto, executa o typecheck e compila o tema gerado.

3. Revise o resultado da análise

cd tema-nuvler

nuvler theme validate
npm run typecheck
npm run build

Confira principalmente:

• migration-report.json: entrypoint, dependências classificadas, componentes, avisos e arquivos adaptados;
• src/migrated/source: árvore React original ativa, com conteúdo adaptado para o Nuvler;
• nuvler.home.json: seções vazias reconhecidas, prontas para receber conteúdo do Nuvler;
• migration-content-seed.json: textos, links e referências de mídia extraídos do projeto original para cadastro no painel;
• migration-content-map.json: relação entre componentes e campos disponíveis no painel;
• CONTENT_SETUP.md: ordem, valores encontrados e instruções para criar cada seção no painel;
• src/components e src/sections: adaptadores do Theme SDK;
• src/styles: CSS, CSS Modules ou Tailwind preservados;
• src/assets: fontes exigidas pelos estilos; imagens de conteúdo são fornecidas pelo painel;
• nuvler.theme.json: identidade, versão e compatibilidade do tema.

A migração não transporta APIs, autenticação, router, stores, carrinho, checkout nem outras regras de negócio do projeto original. Revise os avisos do relatório e faça o acabamento visual necessário antes de publicar.

4. Vincule o tema à loja e abra o preview

Copie a chave de desenvolvimento exibida no painel Nuvler e execute:

nuvler theme configure --key CHAVE_COPIADA_DO_PAINEL
npm run dev

A chave configura API, autenticação e tenant. Não é necessário criar .env. O preview utiliza os dados públicos reais da loja autorizada.

5. Valide e publique

npm run typecheck
npm run build
npm run validate
npm run publish

Antes da primeira publicação, defina a versão desejada em nuvler.theme.json. Nas publicações seguintes, incremente essa versão, pois cada versão enviada ao Theme Registry é imutável.

Tutorial 2 — Atualizar o CLI e continuar um tema existente sem perder trabalho

Não execute theme create nem theme migrate sobre um tema existente. A atualização do CLI e do SDK altera apenas dependências e o lockfile; os arquivos em src, public e o manifesto continuam no projeto.

Existem três versões diferentes nesse fluxo:

| Versão | Onde fica | Como é atualizada | | --- | --- | --- | | CLI local | devDependencies.@nuvler/cli | nuvler theme upgrade | | Theme SDK | dependencies.@nuvler/theme-sdk e sdkVersion | nuvler theme upgrade | | Tema publicado | manifesto, package e lockfile | nuvler theme version patch |

Atualizar o CLI ou o SDK não incrementa automaticamente a versão do tema. Isso é intencional para que uma instalação de dependências não reserve uma nova versão imutável no Registry.

1. Proteja o estado atual do tema

Entre na pasta do tema e confira o Git:

cd /caminho/do/meu-tema
git status

Antes de atualizar, salve as alterações em um commit ou stash. Isso permite comparar e reverter somente a atualização de dependências se for necessário.

2. Atualize o CLI global

npm install --global @nuvler/cli@latest
hash -r
nuvler --version

Esse passo atualiza o comando nuvler disponível no terminal, mas não atualiza automaticamente a devDependency do projeto.

3. Atualize o CLI local e o Theme SDK do tema

nuvler theme upgrade

npm ls @nuvler/cli @nuvler/theme-sdk

O comando instala as versões mais recentes de @nuvler/theme-sdk e @nuvler/cli, atualiza as dependências, regenera o lockfile e sincroniza sdkVersion em nuvler.theme.json. Os scripts do projeto usam esse CLI local.

Para versões específicas:

nuvler theme upgrade --sdk 1.3.2 --cli 0.5.2

Não altere o id do tema: ele identifica o mesmo tema no Registry.

4. Confira a autenticação e valide a atualização

nuvler auth status

npm run typecheck
npm run build
npm run validate
npm run dev

O build é executado antes da validação final para que o relatório de performance também consiga medir dist/theme.js. Atualizar o CLI não remove a sessão global nem .nuvler/config.json. Em uma máquina nova ou se a sessão não for mais válida, configure novamente:

nuvler theme configure --key CHAVE_COPIADA_DO_PAINEL

5. Publique uma nova versão do mesmo tema

Depois de testar as alterações, incremente a versão publicada:

nuvler theme version patch

Também são aceitos minor, major ou uma versão exata. O comando sincroniza nuvler.theme.json, package.json e package-lock.json. Para atualizar as ferramentas e incrementar o tema em uma etapa:

nuvler theme upgrade --bump patch

Em seguida, confira e publique:

nuvler theme validate
npm run publish

Não reutilize uma versão já publicada. O Registry retornará que a versão é imutável. Um tema de cliente é enviado ao Theme Registry; não é necessário executar npm publish para ele.

Se o terminal continuar mostrando uma versão global antiga, verifique o executável encontrado com command -v nuvler. Como alternativa segura a uma instalação global sem permissão, use npx @nuvler/cli@latest; evite instalar o CLI com sudo.

Ajuda

nuvler --help
nuvler auth --help
nuvler theme --help
nuvler theme <comando> --help

Autenticação

nuvler auth login

Autentica manualmente o desenvolvedor. Esse fluxo é útil para quem trabalha na própria plataforma; para temas de clientes, prefira theme configure --key.

nuvler auth login --api-url https://api.exemplo.com/api --token TOKEN

• --token <token>: token de developer obrigatório;
• --api-url <url>: URL da API. Também pode vir de NUVLER_API_URL.

O token é salvo na configuração global do usuário, com permissão restrita, e nunca no repositório do tema.

nuvler auth status

Valida a sessão salva e mostra developer, scopes e quantidade de tenants autorizados.

nuvler auth status

nuvler auth logout

Remove a autenticação salva localmente.

nuvler auth logout

Criação de temas

nuvler theme templates

Lista os templates oficiais disponíveis:

nuvler theme templates

• starter: base enxuta para um tema novo;
• nuvler-default: tema oficial completo;
• nuvler-atelier: tema editorial com visual premium.

nuvler theme create

Cria um projeto novo sem instalar dependências.

nuvler theme create <diretório> [opções]

nuvler theme create meu-tema
nuvler theme create tema-raja --id tema-raja --name "Tema Raja"
nuvler theme create tema-loja --template nuvler-default

• --id <id>: id em kebab-case; por padrão usa o nome do diretório;
• --name <nome>: nome público do tema;
• --template <template>: starter, nuvler-default ou nuvler-atelier; o padrão é starter.

O diretório deve não existir ou estar vazio.

nuvler theme migrate

Analisa um projeto React + TypeScript existente, inicialmente Vite ou Next.js, e gera um projeto Nuvler novo. A origem permanece somente leitura.

nuvler theme migrate <origem> --output <destino> [opções]

nuvler theme migrate ../site-raja --output ./tema-raja
nuvler theme migrate ../site-raja --output ./tema-raja \
  --id tema-raja --name "Tema Raja"

• --output <diretório>: destino obrigatório, novo ou vazio;
• --id <id>: id do tema; por padrão usa o diretório de destino;
• --name <nome>: nome do tema; por padrão usa o nome do projeto original;
• --skip-install: não executa npm install no destino;
• --skip-checks: valida somente o manifesto, sem typecheck e build.

Por padrão, o comando instala dependências, valida o manifesto, executa typecheck e build. O resultado da análise fica em migration-report.json. Detalhes e limitações estão no docs/theme-migration.md.

nuvler theme upgrade

Atualiza o Theme SDK e o CLI local sem alterar a versão publicada do tema:

nuvler theme upgrade
nuvler theme upgrade --sdk 1.3.2 --cli 0.5.2
nuvler theme upgrade --bump patch

• --theme <diretório>: pasta do tema; padrão .;
• --sdk <versão> e --cli <versão>: versão exata ou latest;
• --bump <release>: também incrementa o tema com patch, minor, major ou uma versão exata;
• --skip-install: atualiza somente os metadados e exige versões exatas.

nuvler theme version

Incrementa a versão imutável do tema e mantém manifesto, package e lockfile sincronizados:

nuvler theme version patch
nuvler theme version minor
nuvler theme version 2.0.0

Configuração e preview

nuvler theme configure

Vincula o projeto a um tenant autorizado.

nuvler theme configure --key CHAVE_COPIADA_DO_PAINEL
nuvler theme configure --theme ./meu-tema --key CHAVE --tenant loja-raja
nuvler theme configure --tenant loja-raja

• --theme <diretório>: projeto do tema; padrão .;
• --key <chave>: chave de conexão exibida no painel;
• --tenant <slug-ou-id>: escolhe o tenant quando houver mais de um.

Com --key, o comando valida a chave, configura a autenticação global e salva apenas id, slug e nome do tenant em .nuvler/config.json. Sem --key, ele usa a sessão global existente.

nuvler theme dev

Inicia o preview local usando dados públicos reais da loja.

nuvler theme dev
nuvler theme dev --theme ./meu-tema --port 4322
nuvler theme dev --store loja-raja --api-url https://api.exemplo.com/api

• --theme <diretório>: projeto do tema; padrão .;
• --store <slug>: sobrescreve a loja configurada, desde que autorizada;
• --api-url <url>: sobrescreve temporariamente a API salva;
• --port <número>: porta local; padrão 4321.

A CLI valida a sessão e o tenant, carrega site, Home, catálogo, navegação e conteúdo editorial e monta um ThemeContext. O developer token não é enviado ao preview host nem às requisições públicas.

Validação e artefato

nuvler theme validate

Valida nuvler.theme.json, compatibilidade do SDK/runtime, entrada e estilos. Também exibe um performance budget informativo para CSS, JavaScript client, imagens, fontes e módulos marcados com "use client".

nuvler theme validate
nuvler theme validate --theme ./meu-tema

Limites iniciais:

| Métrica | Budget | | --- | ---: | | CSS compactado com gzip | 50 KiB | | dist/theme.js compactado com gzip | 120 KiB | | Imagens do projeto, total | 5 MiB | | Maior imagem individual | 512 KiB | | Fontes do projeto, total | 400 KiB | | Arquivos de fonte | 4 | | Módulos "use client" | 8 |

O JavaScript só é medido quando dist/theme.js existe; execute nuvler theme build antes de validate para obter essa métrica. Diretórios de build, dependências e artefatos são ignorados ao contar os arquivos-fonte.

Nesta versão, exceder o budget gera ⚠, mas não muda o exit code e não bloqueia a publicação. Erros de manifesto, SDK, runtime ou arquivos obrigatórios continuam bloqueantes.

nuvler theme build

Valida e compila o tema para produção em dist/.

nuvler theme build
nuvler theme build --theme ./meu-tema

O resultado principal é dist/theme.js, acompanhado por dist/theme.css e dist/assets/ quando existirem.

nuvler theme pack

Executa o build, valida a política do artefato e cria o .tgz aceito pelo Theme Registry.

nuvler theme pack
nuvler theme pack --theme ./meu-tema --destination ./releases
nuvler theme pack --skip-build

• --theme <diretório>: projeto do tema; padrão .;
• --destination <diretório>: destino do artefato; padrão artifacts;
• --skip-build: reutiliza um build existente em dist/.

O arquivo segue o formato <id>-<version>.nuvler-theme.tgz. A CLI também calcula tamanho e integridade sha256.

Publicação

nuvler theme publish

Compila, empacota e envia o tema diretamente ao Theme Registry. Esse comando não executa npm publish.

Tema privado de um cliente configurado:

nuvler theme configure --key CHAVE_DO_CLIENTE
nuvler theme publish

Tema de tenant com visibilidade explícita:

nuvler theme publish --visibility private
nuvler theme publish --visibility unlisted
nuvler theme publish --visibility public

Tema oficial para todos, usando uma sessão PLATFORM_ADMIN:

nuvler theme publish --official

Opções:

• --theme <diretório>: projeto do tema; padrão .;
• --destination <diretório>: artefato local; padrão artifacts;
• --api-url <url>: sobrescreve temporariamente a API salva;
• --token <token>: sobrescreve temporariamente a sessão salva;
• --visibility <valor>: private, unlisted ou public;
• --tenant-id <id>: sobrescreve temporariamente o tenant configurado;
• --official: publica como PLATFORM/PUBLIC; exige PLATFORM_ADMIN.

Regras padrão:

• com tenant: ownership TENANT e visibilidade PRIVATE;
• sem tenant: ownership DEVELOPER e visibilidade UNLISTED;
• com --official: ownership PLATFORM, acesso FREE e visibilidade PUBLIC.

Antes de publicar uma alteração, incremente version em nuvler.theme.json. Uma versão publicada é imutável.

Scripts gerados no projeto

Um tema criado pela CLI recebe estes atalhos:

| Script | Comando executado | | --- | --- | | npm run dev | nuvler theme dev --theme . | | npm run validate | nuvler theme validate --theme . | | npm run typecheck | tsc -p tsconfig.json --noEmit | | npm run build | nuvler theme build --theme . | | npm run pack | nuvler theme pack --theme . | | npm run publish | nuvler theme publish --theme . | | npm run upgrade | nuvler theme upgrade --theme . |

Temas externos são publicados no Theme Registry como .nuvler-theme.tgz. O tema oficial @nuvler/theme-default também possui uma distribuição npm, instalada no build do Store para o fallback renderizado no servidor.