Retail React App
O Retail React App é um conjunto de ferramentas e códigos de amostra projetado para ajudar você a começar a desenvolver sua loja virtual com base em APIs e hospedá-la no Managed Runtime. Este guia de arquitetura descreve a estrutura e o conteúdo do Retail React App e destaca sua base flexível e de código aberto.
Todos os projetos criados com o PWA Kit começam com o mesmo conjunto de arquivos. No início de um projeto, esses arquivos são gerados pela execução de um script. Esse processo é descrito em detalhes no guia Como começar.
Para ter uma visão geral de como o Retail React App funciona, comece analisando a estrutura de arquivos dele. Veja aqui uma lista de todos os arquivos e diretórios de um projeto recém-gerado com uma breve descrição de cada um. (As tecnologias mencionadas nas descrições são vistas em mais detalhes um pouco mais adiante nesse guia.)
O Retail React App inclui diversos scripts para automatizar as tarefas rotineiras de desenvolvimento. Use o comando npm run <SCRIPT_NAME> para executá-los no terminal.
Veja aqui uma lista completa de todos os scripts incluídos e uma descrição de cada um deles:
| Nome | Descrição |
|---|---|
analyze-build | Desenvolve o projeto no modo de produção e cria dois relatórios webpack-bundle-analyzer. Use o relatório para monitorar o tamanho do seu pacote de códigos. |
compile-messages | Compila todas as mensagens localizadas no formato AST. |
extract-messages | Extrai automaticamente as mensagens padrão da localidade dos componentes do React. |
format | Formata o código usando Prettier. |
lint | Encontra estilos de códigos inconsistentes usando ESlint. |
lint:fix | Corrige automaticamente erros no ESlint. |
prod:build | Cria o projeto no modo de produção. |
push | Envia por push o pacote de códigos (artefatos do build de produção) para o Managed Runtime. |
save-credentials | Salva as credenciais do Runtime Admin localmente (para o comando push). |
start | Inicia o servidor SSR. |
start:inspect | Inicia o servidor SSR usando um inspetor Node.js. |
start:pseudolocale | Inicia o servidor SSR com uma pseudo-localidade. |
test | Executa testes de unidade usando Jest. |
test:lighthouse | Executa testes Lighthouse. |
test:max-file-size | Executa um teste bundlesize. |
Seu projeto vem com dois conjuntos de testes de exemplo para fins de garantia de qualidade: testes de unidade criados com Jest e React Testing Library(Biblioteca de testes do Reach).
Os testes de unidade são incluídos juntamente com cada componente de página nos respectivos diretórios.
Para iniciar os testes de unidade, execute o comando a seguir em seu terminal:
Para saber mais sobre como testar sua loja (virtual), veja os código-fonte dos conjuntos de testes de exemplo e a documentação de Jest e React Testing Library.
O Retail React App obtém excelentes pontuações de desempenho desde o início, como medido pelo conjunto de teste Lighthouse, do Google. Facilitamos o monitoramento das pontuações do Lighthouse por todo o desenvolvimento usando o script a seguir:
O script executa o Lighthouse três vezes em sua loja (virtual) e carrega as pontuações médias para cada categoria no Google. Por sua vez, o Google usa essas pontuações para gerar um relatório. Um link para o relatório é fornecido pelo script.
Para usar APIs da Salesforce para acessar dados de um comprador, o administrador deve realizar todas as tarefas descritas em Configurar o acesso à API.
Os dados do comprador no Retail React App são acessados através de uma classe chamada CommerceAPI que é criada sobre o cliente commerce-sdk-isomorphic. Você pode personalizar a classe CommerceAPI no app/commerce-api/index.js e configurá-la em app/api.config.js.
A classe CommerceAPI é automaticamente injetada em cada método getProps da página. Por exemplo, você pode acessar o wrapper de API no componente da página, desta maneira:
A wrapper CommerceAPI usa atualmente a Commerce API para produtos, promoções, cheques-presente e pesquisa. Cada um desses recursos é fornecido com seu próprio conjunto de endpoints, que são documentados separadamente na Referência da B2C Commerce API.
Para autorizar solicitações de API em nome de compradores e convidados registrados, a classe CommerceAPI depende de uma Salesforce Commerce API denominada Shopper Login and API Access Service (SLAS).
Para carrinhos e pedidos, a classe CommerceAPI também usa a Open Commerce API (OCAPI).
As instruções para configurar a Salesforce Commerce API (inclusive o SLAS) e a OCAPI são abordadas no guia Configurar o acesso à API.
A biblioteca de componentes Chakra UI é uma nova tecnologia pronta para produção que usamos no Retail React App. Ela inclui mais de 50 componentes de interface de usuário, todos com excelente acessibilidade e usabilidade. Os componentes podem ser personalizados com props de estilo ou usando objetos JavaScript para estilos mais avançados (CSS-in-JS). Todos os componentes do Chakra vêm com estilos de base bem-desenhados que podem ser substituídos por um sistema de temas.
O sistema Chakra Theming se baseia na Styled System Theme Specification (Especificação de tema do Styled System). Você pode personalizar a aparência de seus componentes para atender às necessidades de sua marca ao atualizar os valores no diretório app/theme.
O Theming está disponível para a maioria dos componentes reutilizáveis em app/components, mas não está disponível para páginas, como as Páginas de detalhes do produto e as Página de listagem de produtos. Para alterar o estilo dessas páginas, edite os estilos inline no código-fonte para os respectivos componentes da página em app/pages.
Para incluir ícones SVG personalizados no projeto, adicione-os ao diretório app/assets/svg, importe-os para app/components/icons/index.js e exporte o componente icon React assim: export const MyCustomIcon = icon('my-custom-icon').
Os ícones SVG importados são empacotados em um sprite do SVG no momento da compilação. Por sua vez, o sprite é incluído no HTML renderizado no lado do servidor.
O PWA Kit React SDK é uma biblioteca compatível com o pipeline de renderização isomórfica para as lojas (virtuais) do PWA Kit. Ele contém várias classes, funções e componentes importantes que respaldam o Retail React App. Por exemplo, a função render() no app/ssr.js que inicia todo o processo de renderização e roteamento é importado do SDK.
O SDK abstrai alguns dos detalhes de implementação para renderização no lado do servidor, cache e proxy, e dá a você muitas oportunidades de personalizar a operação deles. Ele também fornece utilidades e ferramentas de uso geral para manter um único conjunto de códigos que pode ser renderizado tanto no lado do cliente quanto no lado do servidor.
A Salesforce mantém o SDK como um pacote npm separado do Retail React App para que os aprimoramentos possam ser feitos de maneira mais rápida.
O PWA Kit React SDK e todo o Retail React App são projetos com código aberto e estão disponíveis no GitHub. Convidamos a todos da comunidade do Commerce Cloud para contribuir!
As tecnologias de código aberto enumeradas nesta seção são as usadas com mais frequência pelo Retail React App. Elas também são as mais difíceis de serem substituídas por alternativas, então as selecionadas não somente pelas características de desempenho que apresentam como também pela reputação que elas têm. Cada uma é ativamente mantida, altamente personalizável e bem-documentada, e amplamente usada.
Veja aqui uma descrição geral breve de cada uma das tecnologias principais, muitas das quais você já pode estar familiarizado:
Babel compila seu código JavaScript para torná-lo compatível com uma ampla variedade de navegadores e ambientes Node.js. Ele transforma sintaxe de linguagem avançada e faz o polyfill de quaisquer recursos que estejam faltando no ambiente.
Express é um framework de servidor web popular e de código aberto. É escrito em JavaScript se executa no ambiente de execução do Node.js. Ele lida com solicitações HTT para as rotas que você define como pontos de entrada para sua loja (virtual).
O Express permite que você defina configurações comuns do servidor web, como a porta de conexão e o local dos modelos para o retorno da resposta. Ele permite que você adicione processamento adicional de solicitações middleware em qualquer ponto do pipeline que processa a solicitação.
Todo o código do lado do servidor para um aplicativo PWA Kit é executado sobre Node.js, um ambiente de execução de código aberto para JavaScript. O ambiente de execução omite APIs JavaScript específicas do navegador e inclui suas próprias APIs para acessar recursos do sistema operacional do host (como o sistema de arquivos), de uma maneira multiplataforma.
O Node.js usa uma arquitetura sem bloqueio ou assíncrona, que é ideal para criar lojas (virtuais) altamente dimensionáveis e com muitos dados.
O React é um framework desenvolvimento pelo Facebook para criar aplicativos de uma única página que fornecem interfaces de usuário rápidas, fluidas e imersivas.
Em um aplicativo React, a interface do usuário é desenvolvida com componentes diferentes que são normalmente organizados em hierarquias complexas. Em um aplicativo React perfeitamente elaborado, cada componente é unicamente responsável por uma tarefa — e geralmente essa tarefa é somente para conter outros componentes.
A hierarquia de componentes no Retail React App está pensada para oferecer extensibilidade. Você pode criar sobre os componentes incluídos ou trocá-los por novos componentes.
Pacotes relacionados ao React:
| Nome | Descrição |
|---|---|
| Loadable Components (Componentes carregáveis) | Agiliza o desempenho por meio da separação de código de pacotes mais extensos. |
| ReactDOM | Fornece métodos específicos ao DOM que podem ser usados no nível superior do seu aplicativo. |
| ReactDOMServer | Fornece o método renderToString() que pré-renderiza HTML no lado do servidor. |
| React Helmet | Ajuda você a gerenciar alterações na tag head do documento |
| React Router | Correlaciona caminhos de URL a componentes do React. Os caminhos podem ser expressos como padrões que são correspondidos do mais específico ao menos específico. |
O Webpack consolida seu código em um ou mais pacotes. Esses pacotes são implantados no Managed Runtime e, então, carregados no navegador como parte do processo de hidratação.
O Retail React App importa configurações Webpack já prontas para o formulário do lado do cliente e do lado do servidor do PWA Kit React SDK. Na maioria dos casos, você não precisa modificar essas configurações, mas caso decida alterá-las, você pode estender a configuração do Webpack em webpack.config.js.
Agora que você está familiarizado com a estrutura e o conteúdo do Retail React App, é hora de saber um pouco mais! Comece vendo o código-fonte, especialmente os componentes de comércio eletrônico em app/pages.