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:

🔨 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.

🪝 integración de "enlaces" @salesforce/commerce-sdk-react: 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.

⚛️ Importantes actualizaciones a la biblioteca de proveedores, incluido apoyo para React 18, Nodo 16 / 18, Chakra 2 y más.

Una de las primeras decisiones que se deben tomar al migrar de v2.7.x a v3.x es si desea aprovechar la extensibilidad de la plantilla. Para poder beneficiarse de él, debe importar al menos un archivo desde @salesforcef/retail-react-app (u otra aplicación extensible). Puede elegir cuántos archivos desea heredar de la plantilla base, pero debe comprometerse a importar al menos uno.

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.

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.

Para aquellos proyectos que intentan actualizar a v3 y continúan usando getProps, envuelva su componente AppConfig con el componente withLegacyGetProps.

Cambie las dependencias en package.json de la siguiente manera:

Actualice los motores en package.json para admitir Node 18 y npm 9 Remueva @chakra-ui/system de peerDependencies en package.json ya que la versión 2 es la última versión principal de Chakra.

Hay un error nswapi, que es una dependencia de jest-environment-jsdom que no es compatible con Chakra 2. Genera un error ':disabled):not([disabled]' no es un selector válido en algunas de las pruebas que usan el componente Modal. Este error solo afecta las pruebas unitarias, no la ejecución del navegador. Usamos npm 8 y agregamos anulaciones para aplicar la versión 2.2.2 del paquete nwsapi, y se elimina el soporte de npm 7.

Agregue una propiedad overrides en package.json para forzar la versión del paquete:

Reinstale las dependencias de su proyecto con npm i.

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 formulario errors objeto a una capa más de destrucción para enlaces en app/components/forms/* ya que errors objeto se ha movido a formState objeto.

2. 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.

Agregue esta función siempre que utilice renderizado condicional. Hay algunos lugares para agregar la función en un proyecto de PWA Kit:

Vea aquí.

Si tiene instalado un complemento del navegador que interfiere con la renderización de DOM, puede obtener un error de hidratación en el pie de página. Por ejemplo, si está utilizando la extensión LastPass, puede ver el error en el componente Subscribe en el pie de página porque LastPass se hace cargo de la renderización del navegador para insertar un ícono que habilite la ventana emergente en el campo. Si esta toma de control ocurre durante el proceso de hidratación, aparece el error. Un truco simple que puede usar sin tener que usar isHydrated() es cambiar el orden de los componentes de entrada de esta manera:

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 altera muchos archivos en la Retail React App. Para tener una idea de la magnitud de los cambios, compare release-2.7.x → release-3.0.x en esta diferencia de Github y busque @salesforce/commerce-sdk-react. En la diferencia, tome nota de todas las adiciones que agregan esta importación.