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 escaparate además de las API y el alojamiento en Managed Runtime. Esta guía de arquitectura para la Retail React App en la versión 2.x del kit de Progressive Web App (PWA):
Todos los proyectos de PWA Kit 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).
1.eslintignore Exclusion rules for ESLint
2.eslintrc.js Code style rules for ESLint
3.gitignore Exclusion rules for git
4.prettierignore Exclusion rules for Prettier code formatting
5.prettierrc.yaml Code formatting rules for Prettier
6├── app/ Application code lives here
7 ├── assets/svg/ SVG icon assets
8 ├── commerce-api/ Commerce API client and hooks
9 ├── components/ React components
10 │ ├── _app Root component
11 │ ├── _app-config Wrapper component for injecting custom code
12 │ └── _error Generic error component
13 │ └── ...
14 ├── constants.js Constants imported throughout the app
15 ├── contexts/ React contexts
16 ├── hoc Contains higher-order components
17 ├── hooks/ React hooks
18 ├── main.jsx Client-side rendering entry point
19 ├── pages/ Retail-oriented pages like home, PLP, and PDP
20 ├── partials/ Partials imported throughout the app
21 ├── request-processor.js Request processing functions (run at CDN edge)
22 ├── request-processor.test.js Tests for request processing functions
23 ├── routes.jsx Maps request paths to route components
24 ├── routes.test.js Tests for mapping request paths to route components
25 └── ssr.js Server-side rendering entry point
26 ├── static/ Static assets
27 │ └── manifest.json Manifest for PWA features like add to home screen
28 │ └── ...
29 ├── theme/ Theme files for components
30 │ ├── components/
31 │ │ ├── base/ Theme files for Chakra UI components
32 │ │ └── project/ Theme files for custom components
33 │ ├── foundations/ Frequently used theme values like colors and spacing
34 │ └── index.js
35 ├── translations/ Translations for react-intl
36 ├── utils/ Utilities imported throughout the app
37babel.config.js Transpilation rules for Babel
38cache-hash-config.json Cache breaking hash used by the CDN
39CHANGELOG.md Chronological list of changes to the template
40├── config/ Configuration files
41 ├── default.js Default configuration file
42 ├── mocks/ Default configuration file with mock values for unit testing
43 └── sites.js Identifies sites configured in Business Manager. Includes localization details.
44jest-setup.js Unit testing setup for Jest
45jest.config.js Unit testing configuration for Jest
46LICENSE Software licensing agreement
47node_modules/ Package dependencies
48package-lock.json Package configuration lock file
49package.json Package configuration
50README.md Basic documentation
51tests/ Unit tests
52worker/ Service workerPara 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:
| Nombre | Descripción |
|---|---|
analyze-build | Arma 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-messages | Compila todos los mensajes localizados en formato AST. |
extract-messages | Extrae automáticamente los mensajes de la configuración local predeterminada de sus componentes React. |
format | Formatea el código con Prettier. |
lint | Encuentra el estilo de código inconsistente con ESlint. |
lint:fix | Corrige automáticamente los errores de ESlint. |
prod:build | Arma el proyecto en modo de producción. |
push | Envía el paquete de código (artefactos de armado de producción) a Managed Runtime. |
save-credentials | Guarda las credenciales Runtime Admin localmente (para el comando de envío). |
start | Inicia el servidor de SSR. |
start:inspect | Inicia el servidor de SSR con el inspector de Node.js. |
start:pseudolocale | Inicia el servidor de SSR con una pseudo configuración local. |
test | Ejecuta pruebas de la unidad con Jest. |
test:lighthouse | Ejecuta pruebas de Lighthouse |
test:max-file-size | Ejecuta 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:
1npm run testPara obtener más información sobre cómo probar su escaparate, 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:
1npm run test:lighthouseEl 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.
Note
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 config/default.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:
1const MyPage = (props) => {
2 const {categories} = props
3 return <div>There are {categories.length} categories.</div>
4}
5
6MyPage.getProps = async ({api}) => {
7 categories = await api.shopperProducts.getCategory({
8 parameters: {id: categoryId, levels: 0}
9 })
10
11 return {categories}
12}El contenedor CommerceAPI utiliza actualmente la API de Commerce para los productos, las promociones, los certificados de regalo y la búsqueda. Cada característica cuenta con su propio conjunto de puntos de conexión, que se documentan por separado en la referenciade 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.
Note
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 escaparates 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:
| Nombre | Descripción |
|---|---|
| Componentes cargables | Acelera el rendimiento mediante la división del código de los paquetes más grandes. |
| ReactDOM | Proporciona métodos específicos del DOM que se pueden utilizar en el nivel superior de su aplicación. |
| ReactDOMServer | Proporciona el método renderToString() que prerenderiza el HTML del lado del servidor. |
| React Helmet | Le ayuda a gestionar los cambios a la etiqueta head del documento. |
| Router de React | Mapea 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 listas para usar para el lado del cliente y el lado del servidor desde el SDK de React del PWA Kit. 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.
app/pages.
j