File di configurazione

Con i file di configurazione è possibile personalizzare molti aspetti del funzionamento dell'applicazione PWA Kit, tra cui: accesso API, formattazione degli URL, gestione di più siti, invio delle richieste a un proxy e rendering di lato server.

Un file di configurazione può essere scritto nel linguaggio preferito tra JavaScript, YAML o JSON. Sono supportate le seguenti estensioni file: .js, .yml, .yaml e .json.

Un progetto PWA Kit creato con il modello Retail React App presenta un solo file di configurazione: app/config/default.js. Gli oggetti di configurazione che esporta sono impostati sulla base delle opzioni fornite a pwa-kit-create-app, ma è possibile aggiornare la configurazione in qualsiasi momento. Dopo la generazione iniziale del progetto, sono spesso necessari aggiornamenti per mantenere la sincronizzazione con le modifiche alle istanze B2C Commerce.

Per supportare il rendering isomorfo, i valori di configurazione vengono serializzati nella pagina. Non includere segreti nella configurazione.

È possibile sostituire default.js o completarlo con ulteriori file di configurazione perché PWA Kit supporta le configurazioni specifiche per ambiente, illustrate in seguito in questa guida.

Iniziare esaminando le proprietà e gli oggetti di configurazione specifici disponibili in default.js o in qualsiasi file di configurazione.

La stringa di progetto che associa l'applicazione a Managed Runtime non fa parte di un file di configurazione, ma si trova nella proprietà name nella parte superiore del file package.json alla radice della directory di progetto. Dopo la generazione iniziale del progetto è possibile modificare il valore di name in base all'ID progetto visualizzato in Runtime Admin.

Prima della versione 1.5.0 di PWA Kit queste impostazioni si trovavano in app/api.config.js.

Per configurare l'accesso a B2C Commerce API e Open Commerce API (OCAPI), è possibile modificare l'oggetto app.commerceAPI esportato dal file di configurazione.

Di seguito è riportato uno snippet di codice annotato con valori di esempio:

Per configurare l'accesso ad Einstein API, è possibile modificare l'oggetto app.einsteinAPI.

Di seguito è riportato un altro snippet di codice annotato con valori di esempio:

Per ulteriori informazioni sulla classe CommerceAPI che utilizza l'oggetto di configurazione nel precedente snippet di codice, consultare la guida sull'architettura Retail React App.

Per ulteriori informazioni sulle attività di impostazione in Account Manager e Business Manager per abilitare l'accesso API per un'istanza di B2C Commerce, consultare la guida Impostazione dell'accesso API.

È possibile personalizzare il modo in cui gli URL di storefront vengono formattati nell'oggetto app.url.

L'oggetto app.url è configurato con i seguenti valori per impostazione predefinita:

Con queste impostazioni predefinite, sia il sito corrente sia l'impostazione locale vengono visualizzati nel percorso URL.

È possibile scegliere in che modo viene (o non viene) visualizzata l'impostazione locale corrente nell'URL impostando url.locale su uno dei seguenti valori:

path: l'impostazione locale è inclusa nel percorso URL. Esempio: /en-US/women/dress
query_param: l'impostazione locale è inclusa come parametro di query. Esempio: /women/dress?locale=en-US
none: l'impostazione locale non è inclusa nell'URL. Esempio: /women/dress

url.showDefaults: questo valore booleano determina se i valori predefiniti del sito o dell'impostazione locale vengono visualizzate nell'URL. Impostazione predefinita: false.

I siti configurati per l'applicazione vengono estratti nel relativo file denominato config/sites.js. Questo file viene importato in ogni file di configurazione ed esportato nell'oggetto app. Separando i file in questo modo, è possibile sincronizzare più facilmente i siti supportati dall'applicazione e i siti definiti nel back-end di Business Manager. (Se si preferisce, è possibile definire i siti direttamente nel file di configurazione.)

L'oggetto app contiene anche altre impostazioni per la gestione di più siti e dei relativi alias. Queste impostazioni sono illustrate più dettagliatamente nella guida Siti multipli.

L'invio delle richieste a un proxy è configurato nella matrice ssrParameters.proxyConfigs, illustrata dettagliatamente nella guida Invio delle richieste a un proxy.

Prima della versione 1.5.0 di PWA Kit queste impostazioni si trovavano in package.json.

La tabella seguente riporta le opzioni di configurazione correlate al rendering di lato server. Queste opzioni non fanno parte dell'oggetto app e vengono espresse come singole proprietà dell'oggetto exports principale.

Proprietà	Descrizione
`ssrParameters.ssrFunctionNodeVersion`	Stringa che determina quale versione di Node utilizzare per eseguire l'App Server. Valori ammessi: `16.x`.
`ssrEnabled`	Valore booleano che abilita o disabilita la creazione dei file necessari per il rendering di lato server. L'impostazione di questo valore su `false` è deprecata da agosto 2021.
`ssrOnly`	Matrice di espressioni glob, in cui `` è un carattere jolly corrispondente a zero o più istanze di qualsiasi carattere. Determina quali file sono disponibili esclusivamente per il sistema di rendering di lato server e non* attraverso il percorso `/mobify/bundle/`. Valori predefiniti per un progetto appena generato: `['ssr.js', 'ssr.js.map', 'node_modules/*/.*']`
`ssrShared`	Matrice di espressioni glob, in cui `` è un carattere jolly corrispondente a zero o più istanze di qualsiasi carattere. Determina quali file sono* disponibili per il sistema di rendering di lato server e attraverso il percorso `/mobify/bundle/`. Valori predefiniti per un progetto appena generato:

È possibile includere nella directory app/config/ più file di configurazione, compresi quelli per ambienti specifici.

Grazie alle configurazioni specifiche per ambiente, le distribuzioni possono risultare più efficaci e flessibili. Ad esempio, è possibile:

Distribuire un singolo bundle a più ambienti Managed Runtime e fare in modo che ciascun ambiente si colleghi a un'istanza di B2C Commerce diversa.
Collegarsi alla propria On-Demand Sandbox durante lo sviluppo locale, ma a istanze diverse in caso di distribuzione su Managed Runtime.

Per creare un file di configurazione specifico per ambiente, seguire le stesse convenzioni utilizzate in default.js, ma utilizzare il nome dell'ambiente target di destinazione come nome di base del file. Utilizzare uno dei formati di file supportati e la corrispondente estensione. Esempi: production.js, staging.json.

Un'applicazione PWA Kit sceglie il file di configurazione corretto da caricare effettuando una ricerca in app/config e ponendo le seguenti domande nell'ordine indicato:

Esiste un file che corrisponde al nome dell'ambiente attualmente in esecuzione su Managed Runtime?
In caso di esecuzione in locale, esiste un file denominato local con un'estensione supportata?
Se non è ancora stato trovato alcun file di configurazione, esiste un file denominato default con un'estensione supportata?

Non appena la risposta a una di queste domande è "affermativa", PWA Kit interrompe la ricerca e carica il file in questione.

Se due file hanno lo stesso nome di base ma estensioni diverse, viene scelta l'estensione a cui è assegnata la massima priorità. Alle estensioni file supportate viene assegnata una priorità nel seguente ordine, dalla priorità massima alla priorità minima: .js, .yml, .yaml o .json. Ciò significa che tra default.js e default.json PWA Kit carica default.js perché ha la priorità massima.