Debugging 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.

General Troubleshooting

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 Getting 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.

Query Parameters for Debugging

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 mobify_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 mobify_pretty 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).

Debugging Locally

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.

Google Chrome

  1. Open a terminal (or the Command Prompt on Windows).
  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.

Visual Studio Code

  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.