Configurar el entorno local

Esta guía cubre cómo configurar su entorno local para desarrollar con PWA Kit.

Recomendamos utilizar un sistema operativo basado en Unix para el desarrollo del PWA Kit, como por ejemplo:

Usuarios de Windows: Consulte las recomendaciones oficiales de Microsoft para desarrolladores de Node.

Debe instalar versiones específicas de Node y Node Package Manager (NPM) que sean compatibles con Managed Runtime.

Vaya a la página de descarga Node 18.x para descargar el instalador correcto para su computadora.

Usuarios de Windows: Descargue el archivo .msi que corresponda a su procesador. Por ejemplo, si tiene un procesador Intel de 64 bits, deberá elegir el instalador x64.

Usuarios de Mac: Descargue el archivo .pkg.

Usuarios de Apple Silicon: Si todavía no instaló Rosetta, ejecute softwareupdate --install-rosetta.

Usuarios de Linux: Descargue el archivo -linux que corresponda a su procesador. Por ejemplo, si tiene un procesador Intel de 64 bits, deberá elegir el instalador linux-x64 en su formato de archivo preferido.

Ahora que ha descargado el instalador de Node apropiado, ábralo y complete las instrucciones de instalación.

Cuando el instalador se lo pida, acepte la opción predeterminada de instalar también el runtime de Node.js, instale el Administrador de paquetes de Node y añada el runtime de Node.js a su ruta.

Antes de continuar, compruebe que las versiones correctas de Node y NPM estén instaladas:

  1. Abra una terminal.
  2. Ejecute node -v.
  3. Asegúrese de que arroje como respuesta v18.16.1 (o la última versión de 18.x).
  4. Ejecute npm -v.
  5. Asegúrese de que arroje como respuesta 9.5.1 (o la última versión incluida en Node 18.x).

Si tiene una versión diferente de NPM instalada, puede instalar la versión 9.5.1 manualmente de la siguiente manera:

  1. Abra una terminal.
  2. Ejecute npm install -g npm@9.5.1.
  3. Ejecute npm -v de nuevo.
  4. Asegúrese de que arroje 9.5.1 como respuesta.

Si quiere gestionar varias versiones de Node en Windows, le recomendamos utilizar Node Version Switcher o Volta. No recomendamos el Node Version Manager (NVM) de Corey Butler para Windows porque hemos encontrado problemas con él durante nuestras pruebas.

Para los usuarios de Mac y Linux, recomendamos instalar Administrador de la versión de Node.

Cada escaparate del PWA Kit debe tener un proyecto creado en Runtime Admin para gestionar las implementaciones.

Antes de poder usar Managed Runtime y Runtime Admin, deben estar habilitados y debe solicitar acceso a ellos. Para habilitar Managed Runtime y Runtime Admin para su organización, comuníquese con su equipo de cuentas de Salesforce. Para obtener acceso, pídale a su administrador de Commerce Cloud que agregue uno de los siguientes roles a su cuenta mediante Account Manager: Usuario de Managed Runtime o Managed Runtime Admin.

Si usted o alguien de su equipo aún no lo ha hecho, a continuación se explica cómo crear un proyecto en Runtime Admin:

  1. Inicie sesión en Runtime Admin.
  2. Haga clic en New Project (Proyecto nuevo).
  3. Escriba un nombre para el proyecto.
  4. Haga clic en Create Project (Crear proyecto).

Anote el código de identificación del proyecto porque lo necesita para generar archivos de proyecto para el desarrollo.

Cuando se crea un proyecto por primera vez, el sitio no es accesible en la web hasta que se implementa la infraestructura necesaria en la nube. El proceso de implementación puede durar hasta 40 minutos.

Para obtener más información sobre lo que puede hacer en Runtime Admin, consulte nuestra guía de Administración de Managed Runtime.

La mayoría de los desarrolladores de PWA Kit comienzan clonando un repositorio que contiene un conjunto de archivos de proyecto generados previamente. (Para aprender a generar un nuevo proyecto, vaya a la siguiente sección).

Después de clonar el repositorio de su proyecto, debe instalar las dependencias de los paquetes:

  1. Abra una terminal.
  2. Cambie al directorio del proyecto.
  3. Ejecute npm ci.

Si ya tiene un proyecto de PWA Kit y ha completado las instrucciones de la última sección, puede ir a la siguiente sección. De lo contrario, debe generar un proyecto.

Para generar un proyecto, abra una terminal y ejecute el siguiente comando. Reemplace ~/PLACEHOLDER-PROJECT-ID con una ruta que incluya el código de identificación del proyecto desde el Runtime Admin:

En el comando npx, puede reemplazar @latest por una versión específica de la Retail React App, como @v3.0.0 o @v2.7.3. Si no especifica una versión, puede obtener resultados inesperados debido al almacenamiento en caché de versiones antiguas.

Cuando se le pida que elija una configuración predeterminada para el proyecto, seleccione una de las siguientes opciones:

  • retail-react-app-demo: Use la plantilla de escaparate de la Retail React App y use el sandbox de demostración para el backend. No se requiere ninguna otra configuración.
  • retail-react-app: Use la plantilla de escaparate de Retail React App y use su instancia de B2C Commerce para el backend. Debe proporcionar los valores de configuración.

Cuando se utiliza la configuración predeterminada retail-react-app, el script del generador le pide que proporcione varios valores de configuración. Estos valores de configuración asocian su nuevo proyecto de PWA Kit con un proyecto correspondiente en la herramienta de Runtime Admin y una instancia de B2C Commerce.

La siguiente tabla proporciona más información sobre cada valor de configuración del proyecto y dónde encontrarlos. Los valores de configuración también se tratan con más detalle en la documentación de la API de B2C Commerce. Consulte URL base y formación desolicitudes.

Valor de configuraciónMás información
Código de identificación de proyecto en Managed Runtime AdminAdministración de Managed Runtime cubre cómo crear un proyecto y buscar el código de identificación de proyecto de un proyecto existente.
  • Ejemplo: example-project
URL para su instancia de B2C Commerce¿Necesita una nueva instancia de B2C Commerce para desarrollo o pruebas? Consulte Crear un On-Demand Sandbox.
  • Ejemplo: https://zzdc-001.dx.commercecloud.salesforce.com
Código de identificación del cliente de API de CommerceEste identificador ya no se encuentra en el Account Manager. Consulte Generar un código de identificación de cliente para el acceso a la API.
  • Ejemplo: 1adba44c-ee9b-41f9-b4bf-1bbc3dda1967
Modo de cliente privado de la API de CommerceEsto alterna si su aplicación usará un flujo de autenticación público o privado para el inicio de sesión de los compradores. Consulte la documentación de inicio de sesión del comprador y uso de un cliente privado de SLAS para obtener más información.
  • Predeterminado: true
Código de identificación del sitio en Business ManagerCadena utilizada para identificar un sitio de comercio electrónico (eCommerce) en particular. Para obtener una lista de sitios disponibles y sus códigos de identificación de sitio asociados en Business Manager, vaya a Administración > Sitios > Administar sitios.
  • Ejemplo: RefArch
Código de identificación de la organización de la API de Commerce en Business ManagerCadena utilizada para identificar su organización para el acceso a la API basado en el realm y la instancia. Para encontrar la identificación de la organización en Business Manager, vaya a Administración > Desarrollo del sitio > Configuración de Salesforce Commerce API.
  • Ejemplo: f_ecom_zzdc_001
Código corto de la API de Commerce en Business ManagerUna cadena de ocho caracteres asignada a un realm con fines de enrutamiento. El código corto se aplica a todo el entorno del realm, en todas las instancias. (El código corto para todos los sandboxes bajo demanda es kv7kzm78). Para encontrar el código corto en Business Manager, vaya a Administración > Desarrollo del sitio > Configuración de Salesforce Commerce API.
  • Ejemplo: kv7kzm78
Código de identificación de cliente de la API en el Einstein ConfiguratorConsulte la documentación de la API de Einstein para desarrolladores de Commerce Cloud y acceda al Einstein Configurator directamente.

Después de generar un proyecto, le recomendamos que envíe los archivos del proyecto generado a un repositorio y comparta el repositorio con los desarrolladores de su escaparate.

Los valores de configuración de un proyecto se pueden editar después de que se haya generado un proyecto también. Consulte los Archivos de configuración para obtener más información.

No se olvide actualizar la configuración cada vez que cambie alguno de estos valores, por ejemplo, cuando personalice los archivos del proyecto para trabajar con una instancia diferente de B2C Commerce.

Para iniciar su servidor web para el desarrollo local, ejecute el siguiente comando desde el directorio de su proyecto:

Ahora que el servidor de desarrollo se está ejecutando, puede abrir un navegador y obtener una vista previa de su escaparate:

Puede detener el servidor de desarrollo en cualquier momento utilizando el atajo de teclado Control+C.

Para obtener una vista previa de una página renderizada en el lado del servidor, añada la cadena de consulta ?__server_only a la URL que desea previsualizar. Por ejemplo, puede probar la versión de www.example.com renderizada del lado del servidor visitando la URL www.example.com?__server_only.

  • Después de clonar un proyecto existente y ejecutar npm ci o de generar un nuevo proyecto, pueden pasar unos minutos antes de que vea alguna actividad en el terminal, así que no cancele el proceso hasta que termine. Además, el software antivirus puede hacer que las instalaciones tarden mucho más de lo habitual (especialmente en Windows).

  • Si obtiene una respuesta de error HTTP 401 desde el extremo authorize, hay un problema de configuración con Shopper Login and API Access Service (SLAS). Para corregir la configuración del SLAS, consulte las instrucciones en Configurar el acceso a la API.