Configurar o ambiente local

Este guia mostra como configurar seu ambiente local para desenvolver com o PWA Kit.

Recomendamos usar um sistema operacional com base em Unix para o desenvolvimento do PWA Kit, como:

Usuários do Windows: Veja as recomendações oficiais da Microsoft para desenvolvedores Node.

Você precisa instalar versões específicas do Node e do Node Package Manager (NPM) que sejam compatíveis com o Managed Runtime.

Acesse a página de download do Node 18.x para baixar o instalador correto para sua máquina.

Usuários do Windows: Faça download do arquivo .msi que corresponde a seu processador. Por exemplo, se você tem um processador Intel de 64-bit, então baixe o instalador x64.

Usuários de Mac: Faça download do arquivo .pkg.

Usuários de Apple: Se ainda não instalaram o Rosetta, execute softwareupdate --install-rosetta.

Usuários de Linux: Faça download do arquivo -linux que corresponde a seu processador. Por exemplo, se você tem um processador Intel de 64-bit, então baixe o instalador linux-x64 em seu formato de arquivo favorito.

Agora que você baixou o instalador adequado do Node, abra-o e complete as instruções de instalação.

Quando solicitado pelo instalador, aceite a opção padrão para também instalar o runtime Node.js, instalar o Node Package Manager e adicionar o runtime Node.js a seu caminho.

Antes de prosseguir, verifique se as versões corretas do Node e NPM estão instaladas:

  1. Abra um terminal.
  2. Execute node -v.
  3. Certifique-se de que o comando retorna v18.16.1 (ou a versão 18.x mais recente).
  4. Execute npm -v.
  5. Certifique-se de que o comando retorna 9.5.1 (ou a versão 18.x mais recente incluída no Node).

Se você tem uma versão diferente do NMP instalada, você pode instalar a versão 9.5.1 manualmente, assim:

  1. Abra um terminal.
  2. Execute npm install -g npm@9.5.1.
  3. Execute npm -v novamente.
  4. Certifique-se de que retorne 9.5.1.

Se você quer gerenciar várias versões do Node no Windows, recomendamos o Node Version Switcher ou o Volta. Não recomendamos o Node Version Manager (NVM) for Windows de Corey Butler porque encontramos problemas durante os testes que fizemos.

Para usuários de Mac e Linux, recomendamos instalar o Node Version Manager.

Cada loja do PWA Kit deve ter um projeto criado em Runtime Admin para o gerenciamento das implantações.

Antes de usar o Managed Runtime e o Runtime Admin, eles devem estar habilitados e você deve solicitar acesso a eles. Para habilitar o Managed Runtime e o Runtime Admin para sua organização, entre em contato com a equipe de contas do Salesforce. Para ter acesso, peça ao administrador do Commerce Cloud que adicione uma das seguintes funções à sua conta usando Account Manager: Managed Runtime User ou Managed Runtime Admin.

Caso você ou alguém em sua equipe ainda não tenha feito isso, veja aqui como criar um projeto em Runtime Admin:

  1. Faça logon no Runtime Admin.
  2. Clique em New Project (Novo projeto).
  3. Insira um nome para o projeto.
  4. Clique em Create Project (Criar projeto).

Anote o ID do projeto porque você precisará dele para gerar arquivos de projeto para desenvolvimento.

Ao criar um projeto pela primeira vez, o site não fica acessível na Web até depois que a infraestrutura de nuvem necessária seja implantada. O processo de implantação pode levar até 40 minutos.

Para mais informações sobre o que você pode fazer no Runtime Admin, consulte nosso guia Managed Runtime Administration.

A maioria dos desenvolvedores de PWA Kit começam clonando um repositório contendo um conjunto previamente gerado de arquivos de projeto. (Para saber como gerar um novo projeto, vá para a próxima seção.)

Depois de clonar seu repositório de projeto, instale as dependências do pacote:

  1. Abra um terminal.
  2. Vá para o diretório do projeto.
  3. Execute npm ci.

Se você já tem um projeto criado com o PWA Kit e completou as instruções na seção anterior, vá para a próxima seção. Caso contrário, gere um projeto.

Para gerar um projeto, abra um terminal e execute o comando a seguir: Substitua ~/PLACEHOLDER-PROJECT-ID pelo caminho que inclui o ID do projeto do Runtime Admin:

No comando npx, é possível substituir @latest por uma versão específica do Retail React App, como @v3.0.0 ou @v2.7.3. Se você não especificar uma versão, talvez tenha resultados inesperados devido ao cache de versões antigas.

Ao ser solicitado a escolher uma predefinição para o projeto, selecione uma das opções a seguir:

  • retail-react-app-demo: Use o modelo de loja (virtual) do Retail React App, assim como uma sandbox de demonstração para o back-end. Não é necessário configurar nada mais.
  • retail-react-app: Use o modelo de loja (virtual) do Retail React App e sua própria instância do B2C Commerce para o back-end. Você deve fornecer valores de configuração.

Ao usar a predefinição retail-react-app, o script do gerador solicita que você proporcione diversos valores de configuração. Esses valores de configuração associam seu novo projeto criado com o PWA Kit a um projeto correspondente na ferramenta Runtime Admin e a uma instância do B2C Commerce.

A tabela a seguir tem mais informações sobre cada valor de configuração do projeto e onde encontrá-las. Os valores de configuração também são vistos em mais detalhes na documentação da B2C Commerce API. Consulte URL base e formação de solicitação.

Valor de configuraçãoMais informações
ID do projeto no Managed Runtime AdminO guia Administração do Managed Runtime mostra como criar um projeto e buscar o ID de um projeto existente.
  • Exemplo: example-project
URL para sua instância do B2C CommercePrecisa de uma nova instância do B2C Commerce para desenvolvimento ou teste? Consulte Criar uma On-Demand Sandbox.
  • Exemplo: https://zzdc-001.dx.commercecloud.salesforce.com
.
ID do cliente do Commerce APINão é mais possível encontrar esse identificador no Account Manager. Consulte Gerar uma ID do cliente para acesso à API.
  • Exemplo: 1adba44c-ee9b-41f9-b4bf-1bbc3dda1967
Modo de cliente privado da Commerce APIAlterna se seu aplicativo usará um fluxo de autenticação público ou privado para os compradores fazerem logon. Consulte a documentação de Login do comprador e Usar um cliente privado SLAS para obter mais informações.
  • Padrão: true
ID do site no Business ManagerString usada para identificar um site de comércio eletrônico em particular. Para obter uma lista dos sites disponíveis e seus IDs associados no Business Manager, acesse Administração > Sites > Gerenciar sites.
  • Exemplo: RefArch
ID da organização da Commerce API no Business ManagerString usada para identificar sua organização para o acesso à API com base no realm e na instância. Para conferir o ID da organização no Business Manager, acesse Administração > Desenvolvimento do site > Configurações da Salesforce Commerce API.
  • f_ecom_zzdc_001
Código curto do Commerce API no Business ManagerUma string de oito caracteres designada a um realm para fins de roteamento. O código curto se aplica a todo o ambiente de seu realm, em todas as instâncias. (O código curto para todas as On-demand Sandboxes é kv7kzm78). Para conferir seu código curto no Business Manager, acesse Administração > Desenvolvimento do site > Configurações da Salesforce Commerce API.
  • kv7kzm78
ID do cliente da API no Einstein ConfiguratorVeja a documentação da Einstein API para desenvolvedores do Commerce Cloud e acesse o Einstein Configurator diretamente.

Depois de gerar um projeto, recomendamos que você aloque os arquivos gerados do projeto a um repositório e compartilhe esse repositório com os desenvolvedores da loja (virtual).

Você pode editar os valores de configuração de um projeto mesmo depois de o projeto ter sido gerado. Consulte Arquivos de configuração para saber mais.

Não se esqueça de atualizar a configuração sempre que qualquer um desses valores mudar, por exemplo, quando você personaliza arquivos do projeto para trabalhar com uma instância diferente do B2C Commerce.

Para iniciar seu servidor da web para desenvolvimento local, execute o seguinte comando a partir do diretório de projeto:

Agora que o servidor de desenvolvimento se encontra em execução, você pode abrir um navegador e visualizar sua loja (virtual).

Você pode interromper o servidor de desenvolvimento a qualquer momento usando a atalho do teclado Control+C.

Para visualizar uma página renderizada no lado do cliente, adicione a string de consulta ?__server_only ao URL que você deseja ver. Por exemplo, você pode testar a versão renderizada no lado do servidor www.example.com ao visitar o URL www.example.com?__server_only.

  • Depois de clonar um projeto existente e executar npm ci ou gerar um novo projeto, pode demorar alguns minutos até que você possa ver atividades no terminal, então não cancele o processo até que ele tenha finalizado. Saiba também que o software antivírus (especialmente no Windows) pode fazer com que as instalações demorem mais do que o esperado.

  • Se você obtém uma resposta de erro HTTP 401 do endpoint authorize, então há um problema de configuração com o Shopper Login and API Access Service (SLAS). Para corrigir a configuração do SLAS, veja as instruções em Configurar o acesso à API.