Build Kit

O Build Kit é uma opção para agências que desejam versionar componentes em arquivos locais e sincronizá-los em lote pela API oficial. Ele não substitui a seleção, configuração, prévia ou publicação feita no Template Maker.

O kit não oferece preview local, hot reload, compilação local ou publicação automática da loja.

A Skill de Componentes Customizados, distribuída separadamente, pode auxiliar na autoria, revisão de contratos e preparação do dry-run. Ela não substitui a validação final da API, a prévia visual ou a autorização necessária para sincronizar.

Sobre o Build Kit

O Build Kit é uma referência para autoria local e sincronização de componentes. Ele não oferece preview local, hot reload, compilação local nem suporte a ferramentas específicas.

Use-o como ponto de partida e adapte-o ao fluxo técnico do seu projeto.

Pré-requisitos

• Node.js 20 ou superior.
• Código da loja.
• Token Bearer da API oficial.

Crie .env a partir de .env.example:

SYNC_SHOP_CODE=sua_loja
VNDA_API_TOKEN=seu_token

Variável	Uso
SYNC_SHOP_CODE	Identificador da loja enviado no header X-Shop-Code.
VNDA_API_TOKEN	Token Bearer necessário para enviar alterações.

Estrutura local

Organize cada componente em sua própria pasta. O diretório por tipo é a convenção recomendada.

components/
└── home_sections/
    └── meu_banner/
        ├── meu_banner_settings.json
        ├── meu_banner_schema.json
        ├── _meu_banner.liquid
        ├── _meu_banner.scss
        ├── meu_banner.js
        └── partials/
            └── _item_banner.liquid

O arquivo de settings identifica o componente; o schema define suas opções; Liquid, SCSS e JavaScript formam sua implementação. A pasta partials/ contém subarquivos. Consulte Arquivos e subarquivos.

Para componentes genéricos, o JavaScript principal usa o mesmo nome técnico do componente em snake_case, como meu_banner.js. Alguns tipos possuem nomes fixos no editor: consulte o guia de header, footer, product_block, top_bar, buttons ou icons antes de organizar os arquivos.

O kit pode sincronizar os tipos publicados nesta documentação, inclusive global, buttons e icons. Para estes dois últimos, siga integralmente os contratos de Botões e Ícones.

Mesmo sem campos editáveis, buttons e icons precisam de um arquivo *_schema.json com o schema técnico mínimo:

{
  "component_config": {}
}

Sincronizar

Execute primeiro o dry-run, que lê os arquivos locais e verifica parte do contrato antes de qualquer envio:

npm run sync:staging
npm run sync:production

Para sincronizar de fato:

npm run sync:staging -- --apply
npm run sync:production -- --apply --confirm-production sua_loja

Em produção, --confirm-production deve receber o mesmo valor de SYNC_SHOP_CODE.

O kit encontra todos os componentes locais e, para cada um, cria o que ainda não existe ou atualiza o que já existe. Uma atualização substitui todos os arquivos do componente - equivalente ao PATCH da API, que também faz replace-all na lista de files. Mantenha localmente todos os arquivos que devem continuar existindo. Um arquivo ausente no repositório local é removido do componente na próxima sincronização.

Se o componente foi editado pelo editor ou pela API entre duas sincronizações, faça GET /maker/component-external/{id} para recuperar o estado atual antes de sobrescrevê-lo.

O dry-run não substitui a validação final da API nem o teste visual da loja. Depois da sincronização, selecione o componente, configure-o e publique a loja conforme Validação e publicação.

Para detalhes de payload, respostas e erros, consulte Integração pela API.