Debug delle app PWA Kit

I bug e i colli di bottiglia delle prestazioni costituiscono un aspetto inevitabile dello sviluppo di app web. Con PWA Kit è possibile risolvere questi problemi grazie a una serie di strumenti e tecniche di analisi approfondita.

Prima di seguire le istruzioni più specifiche di questa guida, provare la seguente procedura di carattere generale:

Prima di avviare il server di sviluppo locale, verificare che la versione di Node utilizzata sia supportata (fare riferimento alla guida della sezione Inizia).
Controllare che il server di sviluppo sia ancora in funzione e che la porta non sia occupata da un altro processo.
Dopo una modifica di codice, verificare che nel terminale venga visualizzato il messaggio HTTP development server listening prima di ricaricare il browser.
Cercare eventuali errori sia nella console del browser sia nel terminale.
Cercare eventuali risposte di errore di rete utilizzando gli strumenti per sviluppatori del browser. (In Chrome DevTools, passare alla scheda Rete.)
Per identificare gli errori di sintassi e di battitura, utilizzare un formattatore di codice e un linter. In Retail React App sono disponibili i file di configurazione per Prettier (formattatore di codice) e per ESLint (linter).
Controllare le impostazioni antivirus e firewall del computer per individuare eventuali ostacoli che impediscono al codice di eseguire o bloccare le richieste di rete.
Per identificare e analizzare i problemi di prestazioni, utilizzare il Profiler in Chrome DevTools. Per ulteriori informazioni, vedere la seguente guida di Google: Analyze Runtime Performance (Analisi delle prestazioni di runtime). È possibile inoltre installare l'estensione React Developer Tools per Chrome per aggiungere un'ulteriore scheda Profiler in cui visualizzare informazioni simili, ma a livello di componente.

Per facilitare il debug dei problemi di codice di lato server, è possibile aggiungere due parametri di query speciali a qualsiasi URL pubblicato dall'app di e-commerce.

Il parametro di query __server_only interrompe il processo di hydration, in modo tale che la pagina venga visualizzata nel browser esattamente come appare dopo il rendering di lato server. Poiché i motori di ricerca scansionano la versione della pagina renderizzata sul lato server, la possibilità di visualizzare tale versione consente di risolvere i problemi non solo legati al rendering di lato server, ma anche alla SEO.

Il parametro di query __pretty_print aggiunge una formattazione all'oggetto __PRELOADED_STATE__ per renderlo più leggibile. Questo oggetto fornisce uno snapshot dello stato dell'app anteriore all'hydration, che può essere utile durante il debug per sapere se l'oggetto contiene i valori previsti. Per visualizzare i contenuti dell'oggetto, caricare l'app, visualizzare il codice sorgente della pagina e cercare __PRELOADED_STATE__.

L'oggetto __PRELOADED_STATE__ è incluso in un tag <script> nel codice sorgente HTML della pagina, che è stato inizialmente richiesto quando è iniziata l'esecuzione dell'app sul lato server. L'oggetto __PRELOADED_STATE__ contiene valori serializzati restituiti dalla funzione getProps (incluse le versioni di getProps associate al componente _app e al componente page).

Per impostazione predefinita, l'app server visualizza i messaggi della console nel terminale, ma non consente di osservare altrimenti l'esecuzione del codice. Questo limite può rendere complicato il debug del codice che renderizza le pagine sul lato server (o sulla macchina locale).

Per ottimizzare il debug, è possibile avviare il server di sviluppo locale con un comando alternativo che esegue un processo di controllo in Node associabile a un debugger. (Per ulteriori dettagli, consultare la documentazione di Node.)

È possibile associare al processo di controllo di Node il debugger incluso in molti browser ed editor di testo più diffusi. Ecco le istruzioni per Google Chrome e Visual Studio Code.

Aprire un terminale.
Passare alla directory di progetto.
Avviare il server di sviluppo locale utilizzando npm run start:inspect.
Per verificare che il debugger sia in ascolto, cercare il messaggio "Debugger listening" (Debugger in ascolto) nell'output del terminale.
Aprire Chrome e inserire l'URL chrome://inspect.
Fare clic su Open dedicated DevTools for Node (Apri DevTools dedicato per Node).
DevTools si apre in una nuova finestra.
Per verificare che il debugger sia associato, cercare il messaggio "Debugger attached" (Debugger associato) nell'output del terminale.
Impostare punti di interruzione, aggiungere istruzioni debugger ecc.
Caricare una pagina dal server di sviluppo locale in Chrome.
Eseguire il debug utilizzando la finestra dedicata.

Ora è possibile tracciare l'esecuzione del codice di lato server.

Per ulteriori informazioni sul debug con punti di interruzione in DevTools, consultare la seguente guida di Google: Debug JavaScript.

Aprire i file di progetto in Visual Studio Code.
Nella barra dei menu, fare clic su Terminal > New Terminal (Terminale > Nuovo terminale).
Avviare il server di sviluppo locale utilizzando npm run start:inspect.
Aprire il riquadro comandi. Scelta rapida per Windows: Ctrl + Shift + P. Scelta rapida per Mac: Command + Shift + P.
Digitare il comando seguente: “Debug: Attach to Node Process.” (Debug: associa a processo Node.).
Viene visualizzato un elenco dei processi Node. Scegliere il primo dell'elenco.
Per verificare che il debugger sia associato, cercare il messaggio "Debugger attached" (Debugger associato) nell'output del terminale.
Impostare punti di interruzione, aggiungere istruzioni debugger ecc.
Caricare una pagina dal server di sviluppo locale nel browser web.
Eseguire il debug utilizzando il debugger integrato in Visual Studio Code.

Ora è possibile tracciare l'esecuzione del codice di lato server in Visual Studio Code.

Per evitare di dover associare ripetutamente il processo Node, aprire il riquadro comandi e inserire "Debug: Toggle Auto Attach." (Debug: attiva/disattiva associazione automatica.). Attivare l'impostazione Always (Sempre) e riavviare il server di sviluppo locale nel terminale di Visual Studio Code.

Quando l'app viene distribuita su Managed Runtime, il debug remoto non è supportato. Tuttavia, è possibile applicare il comando tail ai registri per qualsiasi ambiente Managed Runtime in tempo reale per diagnosticare eventuali errori di lato server.

Per applicare il comando tail ai registri tramite la riga di comando sono disponibili due opzioni:

Se si lavora in progetto PWA Kit generato nella versione 2.4.1 o successiva, è possibile:

Visualizzare la guida per il comando dei registri: npm run tail-logs -- --help
Applicare il comando tail ai registri per un progetto e un ambiente specifici: npm run tail-logs -- --environment $ENV_ID

I caratteri -- aggiuntivi nei comandi sopra riportati sono obbligatori.

Se si lavora al di fuori di un progetto PWA Kit o in un progetto generato in versioni precedenti alla 2.4.1, è possibile utilizzare npx per:

Visualizzare la guida per il comando dei registri: npx @salesforce/pwa-kit-dev tail-logs --help
Applicare il comando tail ai registri per un ID ambiente e un ID progetto specifici: npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

Al posto degli argomenti --environment e --project, è possibile utilizzare anche gli argomenti -e e -p, che sono più brevi.

Quando si applica il comando tail ai registri, è importante tenere presente i seguenti limiti:

Ciascuna sessione di applicazione del comando tail ai registri terminerà dopo 60 minuti.
Ogni ambiente può supportare fino a 100 sessioni attive di applicazione del comando tail ai registri alla volta tra tutti gli utenti.
Per applicare il comando tail ai registri è necessario disporre delle autorizzazioni di utente amministratore o sviluppatore per il progetto Managed Runtime.