Actualización a v3

A partir de la versión 3, se pueden obtener actualizaciones de @salesforce/retail-react-app agregándola como una dependencia de package.json y habilitando la extensibilidad de la plantilla en su proyecto.

Esta guía cubre cómo actualizar un proyecto de PWA Kit de v2.7.x a v3.0.0.

Hemos agregado muchas características nuevas a PWA Kit v3, que incluyen:

⚛️ Se requiere:

  • getProps Cambio rotundo
  • Actualizaciones importantes de la biblioteca, incluida la compatibilidad con React 18, Node 18, Chakra 2 y más

🔨 Opcional: Extensibilidad de la plantilla — Reduzca en gran medida la huella de código de su proyecto y reduzca el trabajo de desarrollo, el costo de propiedad y los dolores de cabeza por mejoras futuras. Para obtener más información, consulte la guía Extensibilidad de la plantilla.

🪝 Disocia las llamadas de API de la implementación de un proyecto, permite que las llamadas de API se mejoren como dependencia de biblioteca npm y suma muchas de las grandes características (incluida gestión de estado, entre otras) a través de la consulta de TanStack. Consulte la documentación SDK de React de Commerce para comenzar.

Los SDK de PWA Kit se han movido a la organización NPM @salesforce . Para actualizar a la versión 3, instale los nuevos paquetes y reemplace todas las instrucciones de importación para los siguientes paquetes:

  • pwa-kit-react-sdk > @salesforce/pwa-kit-react-sdk@^3
  • pwa-kit-runtime > @salesforce/pwa-kit-runtime@^3
  • pwa-kit-dev > @salesforce/pwa-kit-dev@^3
  • pwa-kit-create-app > @salesforce/pwa-kit-create-app@^3
  • retail-react-app > @salesforce/retail-react-app@^3

A partir de la versión 3.0.0, PWA Kit presenta una nueva estrategia withReactQueryde obtención de datos. Esta estrategia utiliza la biblioteca react-query y le permite escribir ganchos de React para obtener datos de forma isomórfica. getProps A diferencia de , ya no es necesario duplicar la lógica de obtención de datos para el lado del cliente y el lado del servidor. En esta versión, de forma predeterminada, @salesforce/retail-react-app utiliza @salesforce/commerce-sdk-react que funciona con react-query.

  • Puede usar withReactQuery y withLegacyGetProps al mismo tiempo.
  • getProps y shouldGetProps se eliminaron de la plantilla predeterminada de las páginas de Retail React App, pero no están en desuso. Se mantiene el apoyo a largo plazo para estos métodos.

Cambie las dependencias en package.json como se muestra a continuación. Retire @chakra-ui/system de peerDependencies e inclúyalo en dependencies o devDependencies.

Actualice los motores en package.json para admitir Node 18 y npm 9.

Reinstale las dependencias de su proyecto con npm i.

Al migrar de v2.7.x a v3.x, puede elegir si desea usar la extensibilidad de plantillas. Para beneficiarse de él, debe importar al menos un archivo de @salesforce/retail-react-app (u otra plantilla ampliable en el futuro).

A partir de ahí, considere cuántos archivos ha modificado del proyecto original que generó a través de npx pwa-kit-create-app@2.x. Algunos clientes tienen un gran número (quizás cientos) de archivos, pero incluso así, un número significativo puede no modificarse. Esos archivos no modificados son buenos candidatos para importar desde @salesforce/retail-react-app, pero recomendamos realizar este proceso con cuidado y de forma gradual. Muchos archivos en @salesforce/retail-react-app son similares pero se han modificado desde su estado anterior en v2.x de la Retail React App de PWA Kit. En particular, la integración de @salesforce/commerce-sdk-react (los detalles de la migración se tratan con más detalle más adelante) ha provocado que un gran número de archivos cambien en términos de sus importaciones y su estructura de archivos. El directorio completo commerce-api se eliminó de Retail React App.

Al migrar un proyecto para usar la extensibilidad de la plantilla, tenga en cuenta que la versión 2.x de los SDK del PWA Kit y los proyectos generados a través de npx pwa-kit-create-app@2.x no dependen de @salesforce/commerce-sdk-react, mientras que el código más nuevo @salesforce/retail-react-app@^1.x hace un uso intensivo de esta biblioteca, que toca y cambia muchos archivos. Para tener una idea de la magnitud de los cambios, se puede comparar release-2.7.x → release-3.0.x en esta diferencia de Github https://github.com/SalesforceCommerceCloud/pwa-kit/compare/release-2.7.x...release-3.0.x?diff=unified#files_bucket y buscar @salesforce/commerce-sdk-react y tomar nota de todas las adiciones que agregan esta importación.

Si su aplicación intenta compartir código con la versión 2.x (que incluye el directorio app/commerce-api), corre el riesgo de agregar código innecesario a su paquete donde ese código existe (en dos formas muy diferentes) tanto en la carpeta commerce-api como en el módulo npm @salesforce/commerce-sdk-react.

A partir de v3.0.0, el PWA Kit utiliza una estrategia de recuperación diferente withReactQuery. Esta estrategia aprovecha la biblioteca react-query y permite consultas en el paso de renderizado SSR. La @salesforce/retail-react-app utiliza @salesforce/commerce-sdk-react que funciona con react-query.

Para que los enlaces funcionen en el lado del servidor, debe envolver su componente AppConfig con el nuevo componente withReactQuery de orden superior.

Como estrategia de recuperación predeterminada, se requiere un cambio en @salesforce/retail-react-app@^1 para garantizar que las llamadas getProps() heredadas sigan funcionando.

Al completar las actualizaciones de dependencias descritas anteriormente, es posible que encuentre problemas en el proyecto relacionados con las bibliotecas siguientes. En las siguientes secciones proponemos soluciones para resolver estos problemas. Los detalles de su proyecto variarán y las soluciones propuestas deben tratarse como pautas y no como reglas absolutas.

Para la migración de react-hook-form, lea el documento oficial de react-hook-form aquí. En el proyecto PWA, hay dos lugares que requieren cambios:

  1. Mueva el objeto de formulario errors a una capa más de destrucción para los ganchos a app/components/forms/ medida que el errors objeto se ha movido al formState objeto.
  1. Mueva las props de renderización en Controller a la prop field. La firma de devolución de Render devuelve un objeto que contiene field y fieldState.

A partir de React 18, las advertencias de hidratación aparecen como errores en lugar de advertencias como aparecían en React 17. Se requirieron algunas actualizaciones de código para suprimir estos errores potenciales que impiden que la aplicación se cree cuando hay errores de hidratación. Es esencial corregir estos errores para garantizar que la aplicación pueda renderizarse de forma isomórfica. Este error se produce porque no hay coincidencia entre el servidor o el cliente. Si un componente o una página se renderiza de forma condicional, debe asegurarse de que finalice la hidratación antes de renderizar cualquier código específico del cliente.

En su proyecto, cree una función de utilidad para determinar si la hidratación ha terminado. Puede utilizar una variable incorporada proporcionada por window.__HYDRATING__ en pwa-kit-react-sdk.

Si su proyecto utiliza componentes y API de la biblioteca @chakra-ui/react que son diferentes a la plantilla de la Retail React App, revise los documentos oficiales de migración de Chakra 2.

Para admitir Chakra 2, hay algunos archivos que requieren actualizaciones para proyectos basados en la plantilla de la Retail React App:

Elimine allowToggle en el componente Accordion porque allowMultiple y allowToggle no se pueden usar al mismo tiempo en Chakra 2.

En el componente Footer, importar StylesProvider directamente desde @chakra-ui/react está obsoleto. Debes crearlo a través de createStylesContext('Footer') en su lugar.

Configure userEvent antes de llamar a cualquier acción y espere la acción en las pruebas unitarias que usan userEvent porque en la biblioteca de pruebas de React v14.0.0, todas las acciones del usuario son asíncronas y es necesario llamar a setup antes de realizar las acciones del usuario.

Por ejemplo:

Para obtener más información, consulte los documentos oficiales de userEvent de la testing-library.

Alternativamente, para evitar llamar repetidamente a setup() en muchas pruebas unitarias, puede configurar su userEvent en app/utils/test-util.js justo antes de renderizar el componente de prueba y devolverlo junto con los resultados de renderizado para que la prueba pueda realizar las acciones del usuario sin tener que llamar a setup().

En jest-setup, hay una dependencia simulada que puede generar un error acerca de que TextDecoder no está definido en jest-setup.js. Agregue lo siguiente a jest-setup.js:

Al migrar desde la versión 2.x de los SDK del PWA Kit o proyectos generados a través de npx pwa-kit-create-app@2.x, el código @salesforce/commerce-sdk-react se ha refactorizado significativamente para eliminar el directorio app/commerce-api/. En lugar de que esos archivos manejen la solicitud de API y actúen como un SDK, @salesforce/commerce-sdk-react reemplaza esa funcionalidad. La versión v3 de los SDK se correlaciona con la primera versión de @salesforce/retail-react-app@^1.x porque los SDKS usan mucho esta biblioteca.

La implementación de @salesforce/commerce-sdk-react cambia muchos archivos en la Retail React App. Para tener una idea del tamaño de los cambios, compáralos release-2.7.x con release-3.0.x en esta diferencia de GitHub y busca @salesforce/commerce-sdk-react. En el diff, toma nota de todas las adiciones que incluyen esta importación.