Impostazione dell'ambiente locale

Questa guida spiega come impostare l'ambiente locale per lo sviluppo con PWA Kit.

Per lo sviluppo con PWA Kit, si consiglia di utilizzare un sistema operativo basato su Unix, ad esempio:

Windows 10 con il Windows Subsystem for Linux installato
macOS 10.13 o versioni successive
Ubuntu Linux 18.x o versioni successive

Utenti Windows: vedere i consigli ufficiali di Microsoft per sviluppatori Node.

È necessario installare versioni specifiche di Node e Node Package Manager (NPM) supportate da Managed Runtime.

Passare alla pagina di download di Node 18.x per scaricare il programma di installazione appropriato per il proprio computer.

Utenti Windows: scaricare il file .msi corrispondente al processore utilizzato. Ad esempio, se si possiede un processore Intel a 64 bit, scegliere il programma di installazione x64.

Utenti Mac: scaricare il file .pkg.

Utenti Apple Silicon: se non è già stato installato Rosetta, eseguire softwareupdate --install-rosetta.

Utenti Linux: scaricare il file -linux corrispondente al processore utilizzato. Ad esempio, se si possiede un processore Intel a 64 bit, scegliere il programma di installazione linux-x64 nel formato archivio preferito.

Dopo aver scaricato il programma di installazione di Node appropriato, aprirlo e seguire le istruzioni di impostazione.

Quando viene richiesto dal programma, accettare l'opzione predefinita, ovvero installare anche il runtime Node.js, installare Node Package Manager e aggiungere il runtime Node.js al percorso.

Prima di procedere, verificare che siano installate le versioni corrette di Node ed NPM:

Aprire un terminale.
Eseguire node -v.
Assicurarsi che il comando restituisca v18.16.1 (o l'ultima versione 18.x).
Eseguire npm -v.
Assicurarsi che il comando restituisca 9.5.1 (o l'ultima versione inclusa in Node 18.x).

Se la versione di NPM installata è diversa, è possibile installare la versione 9.5.1 manualmente come descritto di seguito:

Aprire un terminale.
Eseguire npm install -g npm@9.5.1.
Eseguire nuovamente npm -v.
Assicurarsi che il comando restituisca 9.5.1.

Per gestire più versioni di Node su Windows, si consiglia di utilizzare Node Version Switcher o Volta. Non è consigliato l'uso di Node Version Manager (NVM) di Corey Butler per Windows perché durante i test sono emerse varie problematiche.

Per gli utenti Mac e Linux, si consiglia di installare Node Version Manager.

Per ogni storefront PWA Kit deve essere creato un progetto in Runtime Admin per la gestione delle distribuzioni.

Before you can use Managed Runtime and Runtime Admin, they must be enabled and you must request access to them. To enable Managed Runtime and Runtime Admin for your organization, reach out to your Salesforce account team. For access, ask your Commerce Cloud administrator to add either one of the following roles to your account using Account Manager: Managed Runtime User or Managed Runtime Admin.

Qualora all'interno del team non si sia già provveduto, creare un progetto in Runtime Admin come descritto di seguito:

Accedere a Runtime Admin.
Fare clic su New Project (Nuovo progetto).
Inserire un nome per il progetto.
Fare clic su Create Project (Crea progetto).

Annotare l'ID progetto perché sarà richiesto per generare i file di progetto per lo sviluppo.

Quando si crea un progetto per la prima volta, il sito non è accessibile sul Web finché l'infrastruttura cloud necessaria non risulta distribuita. Il processo di distribuzione può richiedere fino a 40 minuti.

Per ulteriori informazioni sulle operazioni che possono essere eseguite in Runtime Admin, consultare la guida Amministrazione in Managed Runtime.

La maggior parte degli sviluppatori PWA Kit inizia clonando un repository contenente un set di file di progetto precedentemente generato. (Per informazioni su come generare un nuovo progetto, passare alla sezione successiva.)

Dopo la clonazione di un repository di progetto, è necessario installare le dipendenze di pacchetto:

Aprire un terminale.
Passare alla directory di progetto.
Eseguire npm ci.

Se esiste già un progetto PWA Kit e sono state completate le operazioni descritte nell'ultima sezione, è possibile passare alla sezione successiva. In caso contrario, è necessario generare un progetto.

Per generare un progetto, aprire un terminale ed eseguire il seguente comando. Sostituire ~/PLACEHOLDER-PROJECT-ID con un percorso contenente l'ID progetto da Runtime Admin:

Nel comando npx è possibile sostituire @latest con una versione specifica di Retail React App, ad esempio @v3.0.0 o @v2.7.3. Se non si specifica una versione, è possibile ottenere risultati imprevisti dovuti al caching delle versioni precedenti.

Quando viene richiesto di scegliere un'impostazione di progetto predefinita, selezionare una delle seguenti opzioni:

retail-react-app-demo: utilizzare il modello di storefront Retail React App e la Sandbox demo per il back-end. Non sono richieste ulteriori operazioni di configurazione.
retail-react-app: utilizzare il modello di storefront Retail React App e l'istanza di B2C Commerce per il back-end. È necessario fornire i valori d configurazione.

Quando si utilizza l'impostazione predefinita retail-react-app, lo script di generazione chiede di specificare diversi valori di configurazione. Questi valori associano il nuovo progetto PWA Kit a un progetto corrispondente nello strumento Runtime Admin e a un'istanza di B2C Commerce.

La tabella seguente fornisce ulteriori informazioni sui valori di configurazione di ogni progetto e su dove trovarli. I valori di configurazione sono descritti più dettagliatamente anche nella documentazione di B2C Commerce API. Vedere Configuration Values (Valori di configurazione).

Valore di configurazione	Ulteriori informazioni
ID progetto in Managed Runtime Admin	Amministrazione in Managed Runtime illustra come creare un progetto e cercare l'ID di un progetto esistente. Esempio: `example-project`
URL per l'istanza di B2C Commerce	Si desidera una nuova istanza di B2C Commerce per finalità di sviluppo o di test? Vedere Creazione di un'istanza On-Demand Sandbox. Esempio: `https://zzdc-001.dx.commercecloud.salesforce.com`
ID client Commerce API	Questo identificatore non è più presente in Account Manager. Vedere Generazione di un ID client per l'accesso API. Esempio: `1adba44c-ee9b-41f9-b4bf-1bbc3dda1967`
ID sito in Business Manager	Stringa utilizzata per identificare un particolare sito di e-commerce. Per ottenere un elenco dei siti disponibili e dei relativi ID sito associati in Business Manager, passare ad Amministrazione > Siti > Gestione dei siti. Esempio: `RefArch`
ID organizzazione Commerce API in Business Manager	Stringa utilizzata per identificare l'organizzazione per l'accesso API in base al realm e all'istanza. Per trovare l'ID organizzazione in Business Manager, passare ad Amministrazione > Sviluppo del sito > Impostazioni Salesforce Commerce API. Esempio: `f_ecom_zzdc_001`
Codice breve Commerce API in Business Manager	Una stringa di otto caratteri assegnata a un realm per fini di routing. Il codice breve si applica all'intero ambiente realm, in tutte le istanze. (Il codice breve per tutte le On-Demand Sandboxes è `kv7kzm78`.) Per individuare il codice breve in Business Manager, passare ad Amministrazione > Sviluppo del sito > Impostazioni Salesforce Commerce API. Esempio: `kv7kzm78`
ID client API in Einstein Configurator	Vedere la documentazione Einstein API per sviluppatori Commerce Cloud e accedere ad Einstein Configurator direttamente.

Dopo aver generato un progetto, si consiglia di eseguire il commit dei relativi file generati in un repository e condividere il repository con gli sviluppatori dello storefront.

Dopo che un progetto è stato generato, è possibile inoltre modificare i relativi valori di configurazione. Per ulteriori informazioni, vedere File di configurazione.

Non dimenticare di aggiornare la configurazione ogni volta che tali valori cambiano, ad esempio quando si personalizzano i file di progetto per un'istanza di B2C Commerce diversa.

Per avviare il server web per lo sviluppo locale, eseguire il seguente comando dalla directory di progetto:

Quando il server di sviluppo è in funzione, è possibile aprire un browser e visualizzare in anteprima lo storefront:

Passare a http://localhost:3000/

È possibile arrestare il server di sviluppo in qualsiasi momento utilizzando la scelta rapida da tastiera Control+C.

Per visualizzare in anteprima una pagina renderizzata sul lato server, aggiungere la stringa di query ?__server_only all'URL da visualizzare in anteprima. Ad esempio, è possibile testare la versione renderizzata sul lato server di www.example.com visitando l'URL www.example.com?__server_only.

Dopo aver clonato un progetto esistente e aver eseguito il comando npm ci o aver generato un nuovo progetto, possono essere necessari alcuni minuti prima di visualizzare attività nel terminale. Pertanto, non annullare il processo prima della fine. Inoltre, un eventuale software antivirus (in particolare su Windows) può provocare una durata delle installazioni molto maggiore del solito.
Se si riceve una risposta di errore HTTP 401 dall'endpoint authorize, esiste un problema di configurazione con Shopper Login and API Access Service (SLAS). Per correggere la configurazione SLAS, consultare le istruzioni in Impostazione dell'accesso API.

Dopo aver impostato l'ambiente di sviluppo locale, la fase successiva consiste nell'eseguire il push di un bundle di codice a Managed Runtime e nella sua distribuzione utilizzando Runtime Admin. Dopo aver ottenuto l'accesso a Runtime Admin, è possibile passare all'ultima guida della sezione Inizia: Push e distribuzione dei bundle.