Debug PWA Kit Apps

Bugs and performance bottlenecks are an unavoidable part of web app development. With PWA Kit, you can get to the bottom of these issues with a variety of tools and techniques for examining your app up close.

Before you follow the more targeted advice in this guide, try these general troubleshooting steps first:

  • Double-check that you’re running a supported version of Node (refer to the Get Started guide) before starting your local development server.
  • Confirm that your development server is still running and the port hasn’t been taken over by another process.
  • After a code change, confirm that the message HTTP development server listening appears in the terminal before reloading your browser.
  • Look for errors in both the browser console and in the terminal.
  • Look for network error responses using your browser’s developer tools. (In Chrome’s DevTools, go to the Network tab.)
  • To help identify syntax errors and typos, run a code formatter and a linter. Configuration files are provided for both Prettier (code formatter) and ESLint (linter) in the Retail React App.
  • Check your computer’s antivirus and firewall settings for anything that is preventing your code from running or blocking network requests.
  • To identify and analyze performance issues, use the Profiler in Chrome’s DevTools. For more information, see this guide from Google: Analyze Runtime Performance. You can also install the React Developer Tools extension for Chrome to get another Profiler tab where you can see similar info but at the component level.

There are two special query parameters that you can add to any URL served by your commerce app to help debug issues with server-side code.

The __server_only query parameter stops the hydration process so that the page appears in your browser exactly as it does after server-side rendering. Seeing the server-sided rendered version of the page helps troubleshoot issues not only with server-side rendering, but also with SEO since search engines crawl this version of the page.

The __pretty_print query parameter adds formatting to the __PRELOADED_STATE__ object to make it more readable. This object provides a snapshot into your app’s state before hydration begins, so it can be helpful for debugging to see if it contains the values that you expect. To view the contents of the object, load your app, view the source of the page, and search for __PRELOADED_STATE__.

The __PRELOADED_STATE__ object is included in a <script> tag within the HTML source of the page that was initially requested when your app begins running on the server side. The __PRELOADED_STATE__ object contains serialized values returned from the getProps function (including the versions of getProps that are attached to the _app component and the page component).

By default, the app server displays console messages in the terminal but doesn’t otherwise allow you to observe code execution. This limitation can make it hard to debug the code that renders pages on the server side (or on your local machine).

For enhanced debugging, you can start your local development server with an alternate command that runs an inspector process in Node that a debugger can attach to. (For more details, see the Node documentation.)

You can attach the debugger included in many popular browsers and text editors to Node’s inspector process. Here are instructions for Google Chrome and Visual Studio Code.

  1. Open a terminal.
  2. Go to your project directory.
  3. Start your local dev server using npm run start:inspect.
  4. To confirm that the debugger is listening, look for a “Debugger listening” message in the terminal output.
  5. Open Chrome and enter the URL chrome://inspect.
  6. Click Open dedicated DevTools for Node.
  7. DevTools opens in a new window.
  8. To confirm that the debugger is attached, look for a “Debugger attached” message in the terminal output.
  9. Set breakpoints, add debugger statements, and so on.
  10. Load a page from your local development server in Chrome.
  11. Use the dedicated window for debugging.

Now you can trace the execution of your server-side code!

To learn more about debugging with breakpoints in DevTools, see this guide from Google: Debug JavaScript.

  1. Open your project files in Visual Studio Code.
  2. From the menu bar, click Terminal > New Terminal.
  3. Start your local dev server using npm run start:inspect.
  4. Open the Command Palette. Shortcut for Windows: Ctrl + Shift + P. Shortcut for Mac Command + Shift + P.
  5. Type the following command: “Debug: Attach to Node Process.”
  6. A list of the Node processes appears. Choose the first one in the list.
  7. To confirm that the debugger is attached, look for a “Debugger Attached” message in the terminal output.
  8. Set breakpoints, add debugger statements, and so on.
  9. Load a page from your local development server in your web browser.
  10. Use the integrated debugger in Visual Studio Code for debugging.

Now you can trace the execution of your server-side code in Visual Studio Code!

To avoid having to attach the Node process repeatedly, open the Command Palette and enter “Debug: Toggle Auto Attach.” Toggle the setting to Always and restart your local dev server in the Visual Studio Code terminal.

Use source maps to identify any server-side or client-side errors. Source maps provide a simple error stack trace that pinpoints where an error occurred. For example, the stack trace identifies the file and line number where the error occurred to make troubleshooting easier.

Enabling source maps has a performance impact, so we recommend using this feature in only non-production environments.

To use source maps, you must build your site using PWA Kit version 3.4.x or later. If you have an earlier version, upgrade your project to use PWA Kit 3.4.x.

You have two choices for enabling source maps: use Runtime Admin or use the Managed Runtime API.

  1. Log into Runtime Admin.
  2. Click your project.
  3. Click an environment.
  4. Click Environment Settings.
  5. In the Advanced section, click Edit.
  6. Enable Source Maps.
  7. At the top of the Advanced section, click Update.
  8. Wait for the bundle to finish redeploying.

Call the projects_target_partial_update API endpoint and set enable_source_maps to true. This configures the NODE_OPTIONS Managed Runtime environment variable in your environment with --enable-source-mapsand redeploys the bundle.

  1. When you build your project, generate the ssr.js.map file by using this local environment variable: PWA_KIT_SSR_SOURCE_MAP=true.
  1. Deploy your bundle to Managed Runtime.

After you enable and upload source maps, you can view them using Tail Logs on Managed Runtime.

Using source maps can cause performance issues. For example, there’s latency anytime error.stack is accessed. So when you include console.error(e) in your code, this can slow down your site.

  • New Non-Production Environments: enable_source_maps is set to true.
  • New Production Environments: enable_source_maps is set to false. This behavior helps to avoid potential performance impacts that may arise when the source maps feature is enabled.
  • All Pre-existing Environments: enable_source_maps is set to false.

When your app is deployed to Managed Runtime, remote debugging is not supported. However, you can tail logs for any Managed Runtime environment in real time to help diagnose any server-side errors.

You have two options to tail logs through the command line.

If you are working within a PWA Kit project generated from version 2.4.1 or higher, you can:

  • View help for the logs command: npm run tail-logs -- --help
  • Tail logs for a specific project and environment: npm run tail-logs -- --environment $ENV_ID

The extra -- in the commands above is required.

If you are working outside of a PWA Kit project, or have a project generated from below version 2.4.1, you can use npx to:

  • View help for the logs command: npx @salesforce/pwa-kit-dev tail-logs --help
  • Tail logs for a specific environment ID and project ID: npx @salesforce/pwa-kit-dev tail-logs --environment $ENV_ID --project $PROJ_ID

Instead of --environment and --project arguments, you can also use the shorter -e and -p arguments.

When tailing logs, keep in mind the following constraints:

  • Each log tailing session will terminate after 60 minutes.
  • Each environment can support up to 100 active log-tailing sessions at a time, across all users.
  • To tail logs, you need to be given developer or admin user permissions to the Managed Runtime project.