Conhecendo uma app VTEX IO

Introdução

Antes de começar, é necessário relembrar alguns conceitos importantes para uma maior compreensão do fluxo lógico ao desenvolver uma app.

manifest.json

vendor

Define o nome da conta VTEX que está desenvolvendo a app. Essa conta é responsável pela manutenção e distribuição da app (pode ser instalada em outras contas ou somente na própria)

O vendor vtex é utilizado em casos de apps nativas.

name

Identifica o nome da aplicação. Não deve ter caracteres especiais - exceto - - ou caracteres maiúsculos.

version

Identifica a versão atual da app. Para versionamento, utilizamos a especificação Semantic Versioning 2.0.0. O formato do versionamento é bem definido, com o uso de patches, minors e majors.

Abaixo um resumo da especificação:

• Patches: você deve criar um patch quando está consertando um bug de forma retrocompatível
• Minors: você deve criar uma versão minor quando adicionar funcionalidade de forma retrocompatível.
• Majors: você deve criar uma versão major quando você realiza mudanças incompatíveis de API (o que costumamos chamar de breaking changes)

Exemplo: Se uma API que está na versão 2.3.2 e uma nova funcionalidade não tiver breaking changes, você pode atualizar a versão para 2.4.0.

No momento que o deploy é feito, há um worker chamado housekeeper responsável por atualizar a versão automaticamente para todas as contas. No caso de minors e patches, o housekeeper atualiza a app automaticamente em todas as contas, já que as mudanças são retrocompatíveis. Atualizações de majors, no entanto, possuem breaking changes, por isso o housekeeper não atualiza a app em todas as contas; sendo assim, a atualização deve ser feita manualmente.

builders

O desenvolvimento de apps no VTEX IO utiliza o conceito de Code as Configuration (CaC). Este paradigma é abstraído através do campo de builders que facilita o desenvolvimento, abstraindo a configuração de serviços.

Exemplo: para criar uma extensão no painel administrativo criam-se apps que utilizam o builder de admin.

Ao linkar a app, portanto, uma pasta de nome correspondente é enviada ao seu builder, que, por sua vez, transforma cada arquivo em configuração para o serviço competente.

dependencies

Uma app pode depender de outras aplicações. Esse campo lista todas as dependências necessárias para o correto funcionamento da app.

Exemplo

No exemplo da estrutura do manifest.json abaixo, é possível observar características mencionadas acima. Em particular, a versão é 0.0.1, onde os números são, respectivamente, major, minor e patch.

{
  "vendor": "vtex",
  "name": "countdown",
  "version": "0.0.1",
  "title": "Countdown",
  "description": "Countdown component",
  "defaultLocale": "pt-BR",
  "builders": {
    "messages": "1.x",
    "store": "0.x",
    "react": "3.x"
  },
  "mustUpdateAt": "2019-04-02",
  "scripts": {
    "postreleasy": "vtex publish --verbose"
  },
  "dependencies": {
    "vtex.styleguide": "9.x",
    "vtex.css-handles": "0.x"
  },
  "$schema": "https://raw.githubusercontent.com/vtex/node-vtex-a pi/master/gen/manifest.schema"
}

Linkando uma app e utilizando-a no tema da loja

Introdução

Para desenvolver um bloco de frente de loja, similar aos que oferecemos nativamente no Store Framework, utilizamos a biblioteca de desenvolvimento de UIs React.js.

Um pouco sobre a tecnologia

A unidade básica de desenvolvimento em React é o componente, onde pode ser implementada a interface visual do componente, como também sua lógica de estado, ou recuperação de dados. Seguindo as recomendações mais modernas de desenvolvimento, iremos focar no uso da API de Hooks do React, não utilizando de classes para a construção dos componentes.

No VTEX IO, adotamos Typescript como linguagem padrão para programação frontend. Apesar de ser necessário aprender sintaxes novas, o esforço é rapidamente recompensado! Utilizando Typescript, ganha-se alta previsibilidade de bugs, por oferecer tipagem estática. Além disso, com as IDEs certas, é possível aumentar a velocidade de implementação através de um code completion mais esperto, com a tipagem de objetos no código.

Neste curso, será utilizado exclusivamente Typescript. Caso você não tenha familiaridade com a linguagem, será uma excelente oportunidade de experimentá-la!

Objetivo dessa etapa

Como você já tem familiaridade com o Store Framework, já sabe que utilizamos blocos, como shelf e sku-selector, para a montagem de uma VTEX IO Store. Nesta etapa você irá criar um bloco que será utilizado no tema da home page de sua loja.

Configurando nosso bot de testes

É importante que você tenha nosso bot de testes instalado no repositório deste curso, de forma que possamos acompanhar a sua evolução ao longo do mesmo, mesmo que este seja um curso que não contenha correções automáticas de cada um dos passos. Para fazer a instalação, siga os passos abaixo:

1. Abra a página de instalação do nosso bot de correção e clique em Configure;

2. Selecione a opção Only selected repositories. Então clique em Select repositories e digite store-block;

3. Clique em Sobral/store-block e depois em Install.

   

Atividade

1. No template clonado localmente, abra o arquivo Countdown.tsx:

   //react/Countdown.tsx
   import React from 'react'
   
   interface CountdownProps {}
   
   const Countdown: StorefrontFunctionComponent<CountdownProps> = ({}) => {
     return <div></div>
   }
   
   Countdown.schema = {
     title: 'editor.countdown.title',
     description: 'editor.countdown.description',
     type: 'object',
     properties: {},
   }
   
   export default Countdown

2. Adicione uma tag h1 dentro do nosso componente e linke a app em seu terminal.

   const Countdown: StorefrontFunctionComponent<CountdownProps> = ({}) => {
   -    return <div></div>
   +    return (
   +      <div>
   +        <h1>Teste Countdown</h1>
   +      </div>
   +    )
   }

   IMPORTANTE: Para que o componente seja visto funcionando na loja, é preciso declarar o bloco que a app define no tema. Em primeiro lugar, será necessário ter um tema para adicionar a app, para isso, será necessário cloná-lo do Github. Nesse curso, o Store Theme será utilizado. Para clonar o repositório, basta executar o seguinte comando:

   git clone https://github.com/vtex-apps/store-theme.git
   

3. Com o repositório clonado, vá ao terminal para deslinkar quaisquer temas ou apps que estejam linkados. Para isso, basta digitar o seguinte comando:

   vtex unlink --all
   

4. Com o repositório já clonado, vá até a pasta com cd store-theme; linke o tema no seu workspace.

   vtex link
   

   IMPORTANTE: Apenas para frisar, nesse ponto do passo, você terá dois terminais abertos e rodando vtex link. O primeiro é referente ao link do bloco customizado que você está criando. Já o segundo se refere ao tema utilizado em questão, store-theme, onde você inserirá o seu bloco customizado.

5. Agora, com os dois links ativos (tema e bloco customizado), para que a app seja utilizada no tema, é preciso adicioná-la às suas dependências, que como visto anteriormente, ficam no manifest.json. Dessa forma, adicione ao manifesto do tema, que se encontra na pasta store-theme, "vtex.countdown" como dependência. A versão dela está definida no manifesto da app (0.0.1). Feito isso, o JSON terá mais uma linha, como mostrado abaixo:

   {
       ...
       "dependencies": {
           ...
   +        "vtex.countdown": "0.x",
           ...
       },
       ...
   }

6. Por fim, é preciso adicionar o bloco na loja. Dentro do arquivo store-theme/store/blocks/home/home.jsonc, declare um bloco chamado "countdown".

   {
       "store.home": {
           "blocks": [
               "countdown",
               ...
           ]
           ...
       }
       ...
   }
   

O resultado esperado é encontrar um header na home da sua loja, como a imagem abaixo: