Atualização para a v3

A partir da v3, você pode obter atualizações do@salesforce/retail-react-app adicionando-o como uma dependência no package.json e ativando a extensibilidade de modelos em seu projeto.

Este guia explica como atualizar um projeto do PWA Kit da v2.7.x para a v3.0.0.

Adicionamos vários recursos novos ao PWA Kit v3, incluindo:

🔨 Extensibilidade de modelos: Diminua consideravelmente o tamanho do código de seu projeto e reduza o trabalho de desenvolvimento, o custo de propriedade e problemas futuros com atualizações. Para mais informações, consulte o guia Extensibilidade de modelos.

🪝 Integração de ganchos @salesforce/commerce-sdk-react: Separa as chamadas da API da implementação de um projeto, permite que as chamadas da API sejam atualizadas como uma dependência da biblioteca do npm e traz muitos recursos excelentes (inclusive gerenciamento de estado e outros) por meio doTanStack Query. Consulte a documentação sobre SDK React do Commerce para começar.

⚛️ Atualizações substanciais à biblioteca do fornecedor, inclusive compatibilidade com React 18, Node 16 / 18, Chakra 2 e mais.

Uma das primeiras decisões que devem ser tomadas ao migrar da v2.7 para a v3.x é se você quer fazer uso da extensibilidade de modelos. Para aproveitar o recurso, é preciso importar pelo menos um arquivo do @salesforcef/retail-react-app (ou de outro aplicativo extensível). É possível escolher quantos arquivos devem herdar do modelo-base, mas você precisa importar pelo menos um.

Feito isso, avalie quantos arquivos você modificou em relação ao projeto original gerado via npx pwa-kit-create-app@2.x. Alguns clientes modificam um grande número de arquivos (talvez centenas), mas, mesmo assim, um número significativo pode ficar sem alterações. Esses arquivos não alterados são bons candidatos para importar do @salesforce/retail-react-app, mas recomendamos realizar esse processo de forma cuidadosa e gradual. Muitos arquivos em @salesforce/retail-react-app são parecidos, mas foram alterados em relação ao seu estado anterior na v2.x do Retail React App do PWA Kit. Em especial, a integração @salesforce/commerce-sdk-react (os detalhes da migração são abordados em mais detalhes posteriormente) fez com que um grande número de arquivos mudasse em termos de importação e de estrutura de arquivos. O diretório commerce-api inteiro foi removido do aplicativo Retail React.

Com a v3.0.0, o PWA Kit passa a usar uma estratégia de busca withReactQuery diferente. Essa estratégia faz uso da biblioteca react-query e habilita consultas na transmissão da renderização SSR. O @salesforce/retail-react-app usa @salesforce/commerce-sdk-react, que é desenvolvido com base na react-query.

Para que os ganchos funcionem no lado do servidor, você precisa unir seu componente AppConfig ao novo componente de ordem superiorwithReactQuery.

Para projetos que estão tentando fazer upgrade para a v3 e continuar a usar o getProps, é preciso unir seu componente AppConfig ao componente withLegacyGetProps.

Mude as dependências em package.json da maneira descrita a seguir.

Atualize os mecanismos em package.json para que sejam compatíveis com o Node 18 e com o npm 9. Remova @chakra-ui/system de peerDependencies em package.json já que a versão 2 é a versão principal mais recente do Chakra.

Há um bug nswapi, que é uma dependência de jest-environment-jsdom incompatível com Chakra 2. Ele exibe um erro':disabled):not([disabled]' is not a valid selector em alguns testes que usam o componente Modal. Esse bug só afeta testes de unidade, e não execuções em navegadores. Usamos o npm 8 e incluímos substituições para aplicar a versão 2.2.2 do pacote nwsapi, e a compatibilidade com o npm 7 é removida.

Adicione uma propriedade overrides a package.json para aplicar a versão do pacote:

Reinstale as dependências para o seu projeto com npm i.

Para a migração do react-hook-form, consulte a documentação oficial do react-hook-form aqui. No projeto do PWA, há dois locais que requerem alteração:

1. Mova o objeto errors de formulário para uma camada a mais de desestruturação para ganchos em app/components/forms/* quando o objeto errors for movido para o objeto formState.

2. Mova os props de renderização em Controller para o prop field. A assinatura do callback de Render retorna um objeto que contém field e fieldState.

A partir do React 18, as advertências de hidratação são exibidas como erros, e não como advertências como eram no React 17. Algumas atualizações ao código precisaram ser feitas para suprimir esses erros em potencial que impedem o aplicativo de criar quando há erros de hidratação. É essencial corrigir esses erros para garantir que o aplicativo possa renderizar isomorficamente. Esse erro ocorre porque há uma falta de correspondência entre o servidor e o cliente. Se um componente ou uma página renderiza condicionalmente, você precisa garantir que a hidratação terminou antes de renderizar qualquer código específico do cliente.

Em seu projeto, crie uma função utilitária para determinar se a hidratação terminou. Você pode usar uma variável integrada fornecida por window.__HYDRATING__ em pwa-kit-react-sdk.

Adicione essa função sempre que você usar a renderização condicional. Há poucos locais para adicionar a função em projeto do PWA Kit.

Confira aqui.

Se você tem um plugin de navegador instalado que interfere com a renderização do DOM, você pode receber um erro de hidratação no rodapé. Por exemplo, se você está usando a extensão LastPass, é possível ver o erro no componente Subscribe no rodapé, porque o LastPass assume o controle da renderização do navegador para injetar um ícone e habilitar o pop-up no campo. Se essa tomada de controle acontece durante o processo de hidratação, o erro aparece. Uma dica simples que você pode aplicar sem precisar usar isHydrated() é mudar a ordem dos componentes de entrada da seguinte forma:

Para ser compatível com o Chakra 2, há alguns arquivos que precisam ser atualizados para projetos com base no modelo do Retail React App:

Remova allowToggle no componente Accordion, porque allowMultiple e allowToggle não podem ser usados ao mesmo tempo no Chakra 2.

No componente Footer, a importação de StylesProvider diretamente de @chakra-ui/react foi descontinuada. Agora, a criação precisa ser feita por createStylesContext('Footer').

Configure userEvent antes chamar qualquer ação e espere a ação em testes de unidade que usam userEvent porque, na biblioteca de testes React v14.0.0, todas as ações do usuário são assíncronas e é preciso chamar setup antes de realizar essas ações.

Por exemplo:

Para mais informações, consulte a documentação oficial sobre userEvent na biblioteca de testes.

Como alternativa, para evitar chamar setup() repetidas vezes em vários testes de unidade, configure seu userEvent em app/utils/test-util.js imediatamente antes da renderização do componente de teste e faça com que ele retorne com os resultados da renderização para que o teste possa executar as ações de usuário sem ter que chamar setup().

Em jest-setup, há uma dependência simulada que pode gerar um erro indicando que TextDecoder está indefinido em jest-setup.js. Adicione o seguinte a jest-setup.js:

Ao migrar da versão 2.x dos SDKs ou dos projetos do PWA Kit gerados via npx pwa-kit-create-app@2.x, o código @salesforce/commerce-sdk-react foi refatorado significativamente para remover o diretório app/commerce-api/*. Em vez de aqueles arquivos processarem solicitações da API e agirem como um SDK, @salesforce/commerce-sdk-react substitui essa funcionalidade. A v3 dos SDKs está correlacionada à primeira versão do @salesforce/retail-react-app@^1.x porque os SDKs usam muito essa biblioteca.

A implementação do @salesforce/commerce-sdk-react altera muitos arquivos no Retail React App. Para entender a magnitude das modificações, compare release-2.7.x → release-3.0.x neste relatório de diferenças do Githube pesquise @salesforce/commerce-sdk-react. No relatório de diferenças, observe todas as adições que incluem essa importação.