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:

Windows 10 com Windows Subsystem for Linux instalado
macOS 10.13 ou superior
Ubuntu Linux 18.x ou superior

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 16.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:

Abra um terminal.
Execute node -v.
Certifique-se de que o comando retorna v16.19.1 (ou a versão 16.x mais recente).
Execute npm -v.
Certifique-se de que o comando retorna 8.19.3 (ou a versão 16.x mais recente incluída no Node).

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

Abra um terminal.
Execute npm install -g npm@8.19.3.
Execute npm -v novamente.
Certifique-se de que retorne 8.19.3.

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 criar um projeto e gerenciar as implantações, o Managed Runtime precisa ser habilitado para sua organização, e você deve solicitar acesso no Runtime Admin. Se o Managed Runtime ainda não tiver sido habilitado, entre em contato com a equipe da conta Salesforce. Para solicitar acesso ao Runtime Admin, entre em contato com o administrador do Commerce Cloud e solicite que adicione uma das funções a seguir a sua conta usando o 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:

Faça logon no Runtime Admin.
Clique em New Project (Novo projeto).
Insira um nome para o projeto.
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:

Abra um terminal.
Vá para o diretório do projeto.
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 @v2.0.0 ou @v1.5.2. 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 API do B2C Commerce. Consulte Valores de configuração.

Valor de configuração	Mais informações
ID do projeto no Managed Runtime Admin	O 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 Commerce	Precisa 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 API	Não é mais possível encontrar esse identificador no Account Manager. Veja Gerar uma ID do cliente para acesso à API. Exemplo: `1adba44c-ee9b-41f9-b4bf-1bbc3dda1967`
ID do site no Business Manager	String 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, vá para Administração > Sites > Gerenciar sites. Exemplo: `RefArch`
ID da organização do Commerce API no Business Manager	String usada para identificar sua organização para o acesso à API com base no realm e na instância. Para localizar o ID da organização no Business Manager, vá para Administração > Desenvolvimento do site > Configurações do Salesforce Commerce API. Exemplo: `f_ecom_zzdc_001`
Código curto do Commerce API no Business Manager	Uma 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 ver o código abreviado no Business Manager, vá para Administração > Desenvolvimento do site > Configurações do Salesforce Commerce API. Exemplo: `kv7kzm78`
ID do cliente da API no Einstein Configurator	Veja 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).

Vá para http://localhost:3000/

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.

Agora que seu ambiente de desenvolvimento local está configurado, a próxima etapa é enviar o pacote de código ao Managed Runtime e implantá-lo usando o Runtime Admin. Quando você conseguir acessar o Runtime Admin, estará tudo pronto para dar início ao próximo guia na série “Como começar”: Enviar por push e implantar pacotes.