Retail React App

La Retail React App (aplicación React para venta minorista) es un conjunto de código de muestra y herramientas diseñadas para darle una ventaja en la construcción de su storefront además de las API y el alojamiento en Managed Runtime. Esta guía de arquitectura describe la estructura y el contenido de la Retail React App y destaca su base flexible y de código abierto.

Todos los proyectos del Kit PWA comienzan con el mismo conjunto de archivos. Al inicio de un proyecto, estos archivos se generan ejecutando un script. (Este proceso se describe en su totalidad en la guía Primeros pasos).

Para tener una visión general de cómo funciona la Retail React App, comience por explorar su estructura de archivos. A continuación se muestra una lista de todos los archivos y directorios de un proyecto recién generado con una breve descripción de cada uno. (Las tecnologías mencionadas en las descripciones se tratan con más detalle más adelante en esta guía).

Para automatizar las tareas rutinarias de desarrollo, la Retail React App incluye varios scripts. Utilice el comando npm run <SCRIPT_NAME> para ejecutarlos desde el terminal.

Esta es una lista completa de todos los scripts incluidos junto con una descripción de cada uno:

NombreDescripción
analyze-buildArma el proyecto en modo de producción y crea dos informes webpack-bundle-analyzer. Utilice los informes para monitorear el tamaño del paquete de código.
compile-messagesCompila todos los mensajes localizados en formato AST.
extract-messagesExtrae automáticamente los mensajes de la configuración local predeterminada de sus componentes React.
formatFormatea el código con Prettier.
lintEncuentra el estilo de código inconsistente con ESlint.
lint:fixCorrige automáticamente los errores de ESlint.
prod:buildArma el proyecto en modo de producción.
pushEnvía el paquete de código (artefactos de armado de producción) a Managed Runtime.
save-credentialsGuarda las credenciales Runtime Admin localmente (para el comando de envío).
startInicia el servidor de SSR.
start:inspectInicia el servidor de SSR con el inspector de Node.js.
start:pseudolocaleInicia el servidor de SSR con una pseudo configuración local.
testEjecuta pruebas de la unidad con Jest.
test:lighthouseEjecuta pruebas de Lighthouse
test:max-file-sizeEjecuta una prueba de tamaño de paquete.

El proyecto viene con dos suites de prueba de ejemplo para el control de calidad: pruebas de la unidad creadas con Jest y React Testing Library.

Las pruebas de la unidad se incluyen junto a cada uno de los componentes de la página en sus respectivos directorios.

Para iniciar las pruebas de la unidad, ejecute el siguiente comando en su terminal:

Para obtener más información sobre cómo probar su storefront, revise el código fuente de las suites de prueba de ejemplo y explore la documentación de Jest y la Biblioteca de pruebas de React.

Desde el principio, la Retail React App obtiene excelentes puntuaciones de rendimiento, según las mediciones de la suite de pruebas Lighthouse de Google Facilitamos el seguimiento de las puntuaciones de Lighthouse a lo largo del desarrollo mediante el siguiente script:

El script ejecuta Lighthouse tres veces en el storefront y sube a Google las puntuaciones medias de cada categoría. A continuación, Google utiliza esas puntuaciones para generar un informe. El script emite un vínculo al informe antes de enviarse.

Para utilizar las API de Salesforce para acceder a los datos de los compradores, un administrador debe completar las tareas descritas en Configurar el acceso a la API.

Los datos de los compradores en la Retail React App son accesibles a través de una clase llamada CommerceAPI que se construye sobre el cliente commerce-sdk-isomorphic. Puede personalizar la clase CommerceAPI en app/commerce-api/index.js y configurarla en app/api.config.js.

La clase CommerceAPI se inyecta automáticamente en el método getProps de cada página. Por ejemplo, puede acceder al contenedor de la API desde un componente de la página de esta manera:

El contenedor CommerceAPI utiliza actualmente la API de Commerce para los productos, las promociones, los certificados de regalo y la búsqueda. Cada una de estas características cuenta con su propio conjunto de extremos, que se documentan por separado en la referencia de la API de B2C Commerce.

Para autorizar las solicitudes de API en nombre de los compradores e invitados registrados, la clase CommerceAPI se basa en una Salesforce Commerce API llamada Shopper Login and API Access Service (SLAS).

Para las canastas y los pedidos, la clase CommerceAPI también utiliza la Open Commerce API (OCAPI).

Las instrucciones para configurar Salesforce Commerce API (incluido el SLAS) y OCAPI se encuentran en Configurar el acceso a la API.

La biblioteca de componentes de IU de Chakra es una tecnología nueva, pero lista para la producción, que nos entusiasma utilizar en la Retail React App. Incluye más de 50 componentes de interfaz de usuario, todos ellos con una excelente accesibilidad y usabilidad. Los componentes se pueden personalizar con props de estilo o utilizando objetos de JavaScript para un estilo más avanzado (CSS-in-JS). Todos los componentes de Chakra vienen con estilos de base bien diseñados que pueden reemplazarse con un sistema de tematización.

El sistema de tematización de Chakra se basa en la especificación temática de estilo del sistema. Puede personalizar el aspecto y la sensación de sus componentes para adaptarlos a su marca actualizando los valores en el directorio app/theme.

La tematización está disponible para la mayoría de los componentes reutilizables en app/components pero no está disponible para las páginas como la Página de detalles del producto o la Página de listado de productos. Para cambiar el estilo de estas páginas, edite los estilos entre líneas en el código fuente de los respectivos componentes de página en app/pages.

Para incluir iconos SVG personalizados en el proyecto, añádalos al directorio app/assets/svg, impórtelos en app/components/icons/index.js y exporte el componente React icon de esta manera: export const MyCustomIcon = icon('my-custom-icon').

Los iconos SVG importados se empaquetan en un sprite SVG en el momento de la construcción, y el sprite se incluye en el HTML renderizado del lado del servidor.

El SDK del PWA Kit de React es una biblioteca que soporta el pipeline de renderizado isomórfico para los storefronts del PWA Kit. Contiene muchas clases, funciones y componentes clave que potencian la Retail React App. Por ejemplo, la función render() en app/ssr.js que pone en marcha todo el proceso de renderizado y enrutamiento se importa del SDK.

El SDK abstrae algunos de los detalles de implementación del renderizado del lado del servidor, el almacenamiento en caché y el proxy, a la vez que ofrece muchas oportunidades para personalizar su funcionamiento. También proporciona utilidades y herramientas de propósito general para mantener un único conjunto de código que puede renderizarse tanto del lado del cliente como del lado del servidor.

Salesforce mantiene el SDK como un paquete separado npm de la Retail React App para que se puedan hacer mejoras más fácilmente.

El SDK de React del PWA Kit y toda la Retail React App son proyectos de código abierto disponibles en GitHub. Agradecemos las contribuciones de la comunidad de Commerce Cloud.

Las tecnologías de código abierto que se enumeran en esta sección son las que se utilizan con mayor frecuencia en la Retail React App. También son las más difíciles de sustituir con alternativas, por lo que las seleccionamos no solo por sus características de rendimiento, sino también por su reputación. Cada una recibe mantenimiento constante, es altamente personalizable, está bien documentada y es ampliamente utilizada.

A continuación le ofrecemos una breve visión general de cada una de estas tecnologías básicas, muchas de las cuales probablemente ya le resulten familiares.

Babel compila el código JavaScript para hacerlo compatible con una amplia gama de navegadores y entornos Node.js. Transforma la sintaxis avanzada del lenguaje y polifuncionaliza las características que faltan en el entorno.

Express es un conocido marco de servidor web de código abierto, escrito en JavaScript y que se ejecuta dentro del entorno de ejecución Node.js. Gestiona solicitudes de HTTP para las rutas que definidas como puntos de entrada al storefront.

Express permite configurar los ajustes comunes del servidor web, como el puerto de conexión y la ubicación de plantillas para arrojar una respuesta. También permite añadir middleware adicional para el procesamiento de solicitudes en cualquier punto dentro del pipeline de manejo de solicitudes.

Todo el código del lado del servidor de una aplicación de PWA Kit se ejecuta en Node.js, un entorno de ejecución de código abierto para JavaScript. El entorno de ejecución omite las API de JavaScript específicas del navegador e incluye sus propias API para acceder a las características del sistema operativo del host (como el sistema de archivos) a lo largo de varias plataformas.

Node.js utiliza una arquitectura que no permite bloqueos, o asíncrona, que es ideal para construir storefronts altamente escalables y con gran cantidad de datos.

React es un marco desarrollado por Facebook para crear aplicaciones de una sola página que ofrecen interfaces de usuario rápidas, fluidas e inmersivas.

En una aplicación React, la interfaz de usuario se construye con componentes discretos que suelen estar dispuestos en jerarquías complejas. En una aplicación React bien diseñada, cada componente solo es responsable de una única tarea, y a menudo dicha tarea es simplemente contener otros componentes.

La jerarquía de componentes en la Retail React App está diseñada para ser extensible. Puede construir sobre los componentes incluidos o cambiarlos por otros nuevos.

Paquetes relacionados con React:

NombreDescripción
Componentes cargablesAcelera el rendimiento mediante la división del código de los paquetes más grandes.
ReactDOMProporciona métodos específicos del DOM que se pueden utilizar en el nivel superior de su aplicación.
ReactDOMServerProporciona el método renderToString() que prerenderiza el HTML del lado del servidor.
React HelmetLe ayuda a gestionar los cambios a la etiqueta head del documento.
Router de ReactMapea las rutas de las URL a los componentes de React. Las rutas pueden expresarse como patrones que se emparejan del más específico al menos específico.

Webpack consolida su código en uno o más paquetes. Estos paquetes se implementan en Managed Runtime y finalmente se cargan en el navegador como parte del proceso de hidratación.

La Retail React App importa configuraciones de Webpack ya hechas para el lado del cliente y el lado del servidor del SDK del PWA Kit de React. En la mayoría de los casos, no es necesario cambiar estas configuraciones, pero si lo hace, puede ampliar la configuración de Webpack en webpack.config.js.

Ahora que ya conoce la estructura y el contenido de la Retail React App, es el momento de profundizar en el tema. Comience por explorar el código fuente, especialmente los componentes de comercio electrónico en app/pages.